@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/lifecycle-derivatives.js

@@ -0,0 +1,422 @@
+/**
+ * Derivative lifecycle (FC7 slice 5, 2026-08-29; agent-native "Derivative lifecycle" family; FC7
+ * mandatory state "option exercise, assignment, expiration, physical/cash settlement, and
+ * multiplier changes" and "futures variation margin and contract rolls"): every family here folds
+ * through the ONE reducer kernel a fill uses — one relief law, one lot-opening law, one
+ * cash-booking law — so an exercise relieves option lots and opens underlying lots with exactly
+ * the arithmetic the equivalent fills would.
+ *
+ * Semantics (position currency, multiplier `m`, and terms come from the position — `ensurePosition`
+ * proved them at the opening fill; every event quantity is in contracts, underlying quantities are
+ * `contracts × m`):
+ *
+ * - `derivative.exercise` — a LONG option position. Cash settlement relieves the contracts at the
+ *   intrinsic value per underlying unit (`max(0, S − K)` for a call, `max(0, K − S)` for a put)
+ *   and books `intrinsic × q × m`; the premium is necessarily realized (there is no underlying lot
+ *   to fold it into). Physical settlement relieves the contracts at 0 (`'realize'`: the premium is
+ *   the option's realized loss) or at each lot's own basis (`'fold-into-underlying-basis'`:
+ *   realized 0, the relieved-quantity-weighted premium per underlying unit moves into the
+ *   delivery price), then buys (call) or sells (put) `q × m` of the underlying at the strike with
+ *   the same lot mechanics as a fill; cash moves at the strike.
+ * - `derivative.assignment` — the mirror image for a SHORT option position: the premium received
+ *   is realized (`'realize'`) or improves the delivery price (`'fold'`); a short call delivers
+ *   (sells) the underlying, a short put takes delivery (buys).
+ * - `derivative.expiration` — any option position; the contracts are relieved at 0 and no cash
+ *   moves (a long expires at a loss of its premium, a short keeps it).
+ * - `derivative.multiplier-change` — every open lot's per-unit basis scales by `before / after`
+ *   so `Σ lot.quantity × basis × multiplier` is preserved exactly; the position's multiplier is
+ *   replaced. An option's strike changes only when the event explicitly carries
+ *   `strikePricePerUnitAfter`; the ledger never derives an adjusted strike from the multiplier.
+ * - `derivative.variation-margin` — a `'variation-margin'` position settles
+ *   `Σ (S − lot basis) × lot quantity × m` in cash and as realized P&L (a short lot gains when
+ *   the price falls), and every lot re-bases to `S`; a second settlement at the same price
+ *   realizes 0.
+ * - `derivative.roll` — closes `quantity` of the from-contract at the close price (proceeds for a
+ *   cash-on-trade position, realized P&L for a variation-margin one) and opens the successor with
+ *   the same sign at the open price under the SAME currency, multiplier, and settlement style.
+ *
+ * Reversal: every family here relieves or re-bases lots. Without an effect record an exact
+ * inverse is not provable, so `reverseDerivativeEvent` refuses through the kernel's `infeasible`
+ * (`portfolio.reversal_infeasible`) naming the family and the correcting event to record instead.
+ * A multiplier change is refused too: the applied event carries only the multiplier AFTER, and
+ * the fold does not keep the multiplier before, so the inverse cannot be proven from the fact —
+ * record the multiplier change back to the prior multiplier.
+ *
+ * Package-internal: dispatched from `state.ts`; nothing here is curated public surface.
+ */
+import { ErrorCode, InputError, sideOf } from '../../core/dist/index.js';
+import { accountOf, bookCash, closingCapacity, ensurePosition, finalizePosition, foldPositionLeg, infeasible, recordRealized, relieveQuantity, requireHeldPosition, } from './reducer-kernel.js';
+// ---------------------------------------------------------------------------------------------------
+// Local primitives (candidates for the kernel — named in the slice report)
+// ---------------------------------------------------------------------------------------------------
+/** Signed direction of a held position, as prose. */
+function directionOf(position) {
+    return position.quantity > 0 ? 'long' : 'short';
+}
+/** The position's terms as prose for a teaching: what the account actually holds. */
+function describeTerms(position) {
+    const terms = position.contract;
+    if (terms === undefined) {
+        return `carries no derivative terms (a cash instrument with multiplier ${position.contractMultiplier})`;
+    }
+    if (terms.kind === 'option') {
+        return `is a ${terms.type} option on ${terms.underlyingInstrumentId} struck at ${terms.strikePricePerUnit}`;
+    }
+    return `is a ${terms.kind} on ${terms.underlyingInstrumentId}`;
+}
+/** Book a signed cash amount unless it is exactly zero — a zero leg is not a cash movement. */
+function bookNonZeroCash(account, currency, amount, envelope, settleTimestampMs) {
+    if (amount === 0)
+        return;
+    bookCash(account, currency, amount, envelope.eventId, settleTimestampMs);
+}
+/** The option terms a lifecycle event requires, or the typed refusal naming what is held instead. */
+function requireOptionTerms(functionName, envelope, position, field) {
+    const terms = position.contract;
+    if (terms !== undefined && terms.kind === 'option')
+        return terms;
+    throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' names ${position.instrumentId}, but the ${directionOf(position)} position of ${Math.abs(position.quantity)} in account '${envelope.accountId}' ${describeTerms(position)} — only an option position (a fill with contract.kind 'option') exercises, is assigned, or expires. ${terms === undefined
+        ? 'Record the opening fill with its contract terms, or close the position with a trade.fill.'
+        : `A ${terms.kind} settles through derivative.variation-margin and closes with a trade.fill or a derivative.roll.`}`, {
+        code: ErrorCode.InputOutOfRange,
+        context: { function: functionName, field, eventId: envelope.eventId },
+    });
+}
+/** Explicit derivative terms required by lifecycle events that apply across contract kinds. */
+function requireDerivativeTerms(functionName, envelope, position, field) {
+    if (position.contract !== undefined)
+        return position.contract;
+    throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' names ${position.instrumentId}, but the position in account '${envelope.accountId}' ${describeTerms(position)} and settles '${position.settlementStyle}' — derivative lifecycle events require a fill with explicit contract terms; a multiplier alone is not a derivative identity. Cash-on-trade instruments mark through portfolioSnapshot and close with trade.fill. Record the opening fill with contract.kind and its terms, or use trade.fill to close this position.`, {
+        code: ErrorCode.InputOutOfRange,
+        context: { function: functionName, field, eventId: envelope.eventId },
+    });
+}
+/** Dated contracts may be acted on through their expiry instant, never after it. */
+function requireContractLiveAtEvent(functionName, envelope, terms, field) {
+    if (terms.kind === 'perpetual' || envelope.effectiveTimestampMs <= terms.expiryTimestampMs)
+        return;
+    throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' occurs at ${envelope.effectiveTimestampMs}, after ${field} expired at ${terms.expiryTimestampMs} — a dated contract may be exercised, assigned, adjusted, margin-settled, or rolled only through its expiry instant. Record the event at its actual effective time, or use the appropriate expiration/closing fact.`, {
+        code: ErrorCode.InputOutOfRange,
+        context: {
+            function: functionName,
+            field,
+            eventId: envelope.eventId,
+            effectiveTimestampMs: envelope.effectiveTimestampMs,
+            expiryTimestampMs: terms.expiryTimestampMs,
+        },
+    });
+}
+/** Expiration is valid at or after the contract's declared expiry, never before it. */
+function requireExpiryReached(functionName, envelope, terms) {
+    if (envelope.effectiveTimestampMs >= terms.expiryTimestampMs)
+        return;
+    throw new InputError(`${functionName}: derivative.expiration event '${envelope.eventId}' occurs at ${envelope.effectiveTimestampMs}, before ${envelope.event.eventType === 'derivative.expiration' ? envelope.event.instrumentId : 'the option'} expires at ${terms.expiryTimestampMs} — expiration is inclusive at the declared expiry instant and may be recorded later, but never early.`, {
+        code: ErrorCode.InputOutOfRange,
+        context: {
+            function: functionName,
+            field: 'event.instrumentId',
+            eventId: envelope.eventId,
+            effectiveTimestampMs: envelope.effectiveTimestampMs,
+            expiryTimestampMs: terms.expiryTimestampMs,
+        },
+    });
+}
+/** The one profile-vs-terms law the fill validator enforces, re-applied to a roll's successor. */
+function requireStyleForTerms(functionName, envelope, instrumentId, style, terms, field) {
+    const expected = terms.kind === 'option' ? 'cash-on-trade' : 'variation-margin';
+    if (style === expected)
+        return;
+    throw new InputError(`${functionName}: ${envelope.event.eventType} event '${envelope.eventId}' opens ${instrumentId} as a ${terms.kind} under settlementStyle '${style}' (carried from the closed position), but a ${terms.kind} settles '${expected}' — a roll's successor is the same kind of contract as the position it replaces. Roll into a ${terms.kind} of the same style, or open the successor with its own trade.fill.`, {
+        code: ErrorCode.InputOutOfRange,
+        context: { function: functionName, field, eventId: envelope.eventId },
+    });
+}
+// ---------------------------------------------------------------------------------------------------
+// Exercise and assignment (one settlement law, two directions)
+// ---------------------------------------------------------------------------------------------------
+/** Intrinsic value per underlying unit at settlement price `S` for strike `K`. */
+function intrinsicPerUnit(type, S, K) {
+    return type === 'call' ? Math.max(0, S - K) : Math.max(0, K - S);
+}
+function settleOption(functionName, state, account, envelope, event) {
+    const isExercise = event.eventType === 'derivative.exercise';
+    const position = requireHeldPosition(functionName, account, envelope, event.instrumentId, 'event.instrumentId');
+    const terms = requireOptionTerms(functionName, envelope, position, 'event.instrumentId');
+    requireContractLiveAtEvent(functionName, envelope, terms, 'event.instrumentId');
+    const held = directionOf(position);
+    if ((isExercise && held !== 'long') || (!isExercise && held !== 'short')) {
+        throw new InputError(`${functionName}: ${event.eventType} event '${envelope.eventId}' names ${event.instrumentId}, but account '${envelope.accountId}' holds a ${held} position of ${Math.abs(position.quantity)} contracts — ${isExercise
+            ? 'a holder exercises LONG contracts; a writer is assigned on short ones. Record derivative.assignment instead.'
+            : 'a writer is assigned on SHORT contracts; a holder exercises long ones. Record derivative.exercise instead.'}`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.instrumentId', eventId: envelope.eventId },
+        });
+    }
+    closingCapacity(functionName, envelope, position, event.quantity, 'event.quantity');
+    const q = event.quantity;
+    const m = position.contractMultiplier;
+    const K = terms.strikePricePerUnit;
+    const currency = position.currency;
+    const underlyingUnits = q * m;
+    // The settled side of the underlying: a holder's call takes delivery, a holder's put delivers;
+    // a writer's call delivers, a writer's put takes delivery.
+    const underlyingSide = (isExercise && terms.type === 'call') || (!isExercise && terms.type === 'put') ? 'buy' : 'sell';
+    if (event.settlement.kind === 'cash') {
+        if (event.premiumTreatment !== 'realize') {
+            throw new InputError(`${functionName}: ${event.eventType} event '${envelope.eventId}' settles ${event.instrumentId} in cash with premiumTreatment 'fold-into-underlying-basis', but a cash settlement delivers no underlying lot to fold the premium into — the premium is realized on the option lots. Record premiumTreatment: 'realize'.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: {
+                    function: functionName,
+                    field: 'event.premiumTreatment',
+                    eventId: envelope.eventId,
+                },
+            });
+        }
+        const intrinsic = intrinsicPerUnit(terms.type, event.settlement.settlementPricePerUnit, K);
+        const outcome = relieveQuantity(functionName, state, envelope, position, q, intrinsic, event.lotSelections, 'event.lotSelections');
+        recordRealized(account, event.instrumentId, currency, outcome.realizedPnl);
+        finalizePosition(account, position);
+        // The holder receives the intrinsic value; the writer pays it.
+        bookNonZeroCash(account, currency, (isExercise ? 1 : -1) * intrinsic * underlyingUnits, envelope, event.settleTimestampMs);
+        return;
+    }
+    // Physical settlement. The option lots are relieved at 0 ('realize': the premium is the
+    // option's realized P&L) or at their own basis ('fold': realized 0, the premium travels into
+    // the delivery price as the relieved-quantity-weighted average per underlying unit).
+    const fold = event.premiumTreatment === 'fold-into-underlying-basis';
+    const outcome = relieveQuantity(functionName, state, envelope, position, q, 0, event.lotSelections, 'event.lotSelections');
+    let premiumPerUnit = 0;
+    if (fold) {
+        const premiumPerContract = outcome.relieved.reduce((sum, lot) => sum + lot.costBasisPerUnit * lot.quantity, 0);
+        premiumPerUnit = premiumPerContract / q;
+    }
+    else {
+        recordRealized(account, event.instrumentId, currency, outcome.realizedPnl);
+    }
+    finalizePosition(account, position);
+    // The delivery price per underlying unit: the strike, moved by the folded premium — against
+    // the holder (who paid it) and in favour of the writer (who received it).
+    const premiumSign = (isExercise ? 1 : -1) * (underlyingSide === 'buy' ? 1 : -1);
+    const deliveryPricePerUnit = K + premiumSign * premiumPerUnit;
+    const underlying = ensurePosition(functionName, account, envelope, terms.underlyingInstrumentId, { currency, contractMultiplier: 1, settlementStyle: 'cash-on-trade' }, 'event.instrumentId');
+    foldPositionLeg(functionName, state, account, envelope, underlying, underlyingSide, underlyingUnits, deliveryPricePerUnit, undefined, 'event.lotSelections', `delivers ${terms.underlyingInstrumentId} and`);
+    // Cash moves at the strike: the premium already moved at the option fill.
+    bookNonZeroCash(account, currency, (underlyingSide === 'buy' ? -1 : 1) * K * underlyingUnits, envelope, event.settleTimestampMs);
+}
+// ---------------------------------------------------------------------------------------------------
+// Expiration
+// ---------------------------------------------------------------------------------------------------
+function applyExpiration(functionName, state, account, envelope, event) {
+    const position = requireHeldPosition(functionName, account, envelope, event.instrumentId, 'event.instrumentId');
+    const terms = requireOptionTerms(functionName, envelope, position, 'event.instrumentId');
+    requireExpiryReached(functionName, envelope, terms);
+    closingCapacity(functionName, envelope, position, event.quantity, 'event.quantity');
+    const outcome = relieveQuantity(functionName, state, envelope, position, event.quantity, 0, event.lotSelections, 'event.lotSelections');
+    recordRealized(account, event.instrumentId, position.currency, outcome.realizedPnl);
+    finalizePosition(account, position);
+}
+// ---------------------------------------------------------------------------------------------------
+// Multiplier change
+// ---------------------------------------------------------------------------------------------------
+function applyMultiplierChange(functionName, account, envelope, event) {
+    const position = requireHeldPosition(functionName, account, envelope, event.instrumentId, 'event.instrumentId');
+    const terms = requireDerivativeTerms(functionName, envelope, position, 'event.instrumentId');
+    requireContractLiveAtEvent(functionName, envelope, terms, 'event.instrumentId');
+    const before = position.contractMultiplier;
+    const after = event.contractMultiplierAfter;
+    if (before === after) {
+        throw new InputError(`${functionName}: derivative.multiplier-change event '${envelope.eventId}' sets ${event.instrumentId} to contractMultiplier ${after}, which is what the position in account '${envelope.accountId}' already carries — an unchanged multiplier is not an economic event. Drop the event, or record the adjusted multiplier.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: functionName,
+                field: 'event.contractMultiplierAfter',
+                eventId: envelope.eventId,
+            },
+        });
+    }
+    // Σ lot.quantity × basis × multiplier is preserved exactly: basis' × after = basis × before.
+    for (const lot of position.lots) {
+        lot.costBasisPerUnit = (lot.costBasisPerUnit * before) / after;
+    }
+    position.contractMultiplier = after;
+    // An OCC-style adjustment also restates the strike; the event carries it explicitly — the
+    // ledger never derives a strike from a multiplier ratio.
+    if (event.strikePricePerUnitAfter !== undefined) {
+        if (position.contract?.kind !== 'option') {
+            throw new InputError(`${functionName}: derivative.multiplier-change event '${envelope.eventId}' carries strikePricePerUnitAfter, but ${event.instrumentId} in account '${envelope.accountId}' ${describeTerms(position)} — only an option has a strike to adjust.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: {
+                    function: functionName,
+                    field: 'event.strikePricePerUnitAfter',
+                    eventId: envelope.eventId,
+                },
+            });
+        }
+        position.contract = { ...position.contract, strikePricePerUnit: event.strikePricePerUnitAfter };
+    }
+    finalizePosition(account, position);
+}
+// ---------------------------------------------------------------------------------------------------
+// Variation margin
+// ---------------------------------------------------------------------------------------------------
+function applyVariationMargin(functionName, account, envelope, event) {
+    const position = requireHeldPosition(functionName, account, envelope, event.instrumentId, 'event.instrumentId');
+    const terms = requireDerivativeTerms(functionName, envelope, position, 'event.instrumentId');
+    requireContractLiveAtEvent(functionName, envelope, terms, 'event.instrumentId');
+    if (terms.kind === 'option') {
+        throw new InputError(`${functionName}: derivative.variation-margin event '${envelope.eventId}' names ${event.instrumentId}, but it is an option — option premium cash moves at trade.fill and the position marks through portfolioSnapshot; only a future or perpetual settles variation margin.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.instrumentId', eventId: envelope.eventId },
+        });
+    }
+    if (position.settlementStyle !== 'variation-margin') {
+        throw new InputError(`${functionName}: derivative.variation-margin event '${envelope.eventId}' names ${event.instrumentId}, but the ${directionOf(position)} position of ${Math.abs(position.quantity)} in account '${envelope.accountId}' settles '${position.settlementStyle}' — its cash moved at the fill and it marks to market through portfolioSnapshot; only a 'variation-margin' position (a future or perpetual opened with that settlementStyle) settles daily. Drop the event, or record the position's fills with settlementStyle 'variation-margin'.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.instrumentId', eventId: envelope.eventId },
+        });
+    }
+    const S = event.settlementPricePerUnit;
+    const m = position.contractMultiplier;
+    // Signed by lot direction: a long lot gains when S rises, a short lot when it falls.
+    let amount = 0;
+    for (const lot of position.lots) {
+        amount += (S - lot.costBasisPerUnit) * lot.quantity * m;
+        lot.costBasisPerUnit = S;
+    }
+    bookNonZeroCash(account, position.currency, amount, envelope, undefined);
+    recordRealized(account, event.instrumentId, position.currency, amount);
+    finalizePosition(account, position);
+}
+// ---------------------------------------------------------------------------------------------------
+// Roll
+// ---------------------------------------------------------------------------------------------------
+function applyRoll(functionName, state, account, envelope, event) {
+    const from = requireHeldPosition(functionName, account, envelope, event.fromInstrumentId, 'event.fromInstrumentId');
+    const fromTerms = requireDerivativeTerms(functionName, envelope, from, 'event.fromInstrumentId');
+    requireContractLiveAtEvent(functionName, envelope, fromTerms, 'event.fromInstrumentId');
+    closingCapacity(functionName, envelope, from, event.quantity, 'event.quantity');
+    const sign = from.quantity > 0 ? 1 : -1;
+    const q = event.quantity;
+    const m = from.contractMultiplier;
+    const style = from.settlementStyle;
+    const currency = from.currency;
+    // The successor's terms: the event's own, or — for a perpetual, which carries no expiry — the
+    // closed position's. An option or future successor has its own expiry, so it states its terms.
+    let successorTerms;
+    if (event.contract === undefined) {
+        if (fromTerms.kind === 'perpetual') {
+            successorTerms = fromTerms;
+        }
+        else {
+            throw new InputError(`${functionName}: derivative.roll event '${envelope.eventId}' rolls ${event.fromInstrumentId} (a ${fromTerms.kind} on ${fromTerms.underlyingInstrumentId} expiring at ${fromTerms.expiryTimestampMs}) into ${event.toInstrumentId} without contract terms — a successor ${fromTerms.kind} has its own expiry, and the ledger never copies one. Record event.contract with the successor's terms.`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field: 'event.contract', eventId: envelope.eventId },
+            });
+        }
+    }
+    else {
+        successorTerms = event.contract;
+    }
+    requireContractLiveAtEvent(functionName, envelope, successorTerms, 'event.contract');
+    if (successorTerms.kind !== fromTerms.kind) {
+        throw new InputError(`${functionName}: derivative.roll event '${envelope.eventId}' rolls ${event.fromInstrumentId}, a ${fromTerms.kind}, into ${event.toInstrumentId} described as a ${successorTerms.kind} — a roll closes one contract and opens its successor of the SAME kind (the multiplier and settlement style carry over). Close ${event.fromInstrumentId} with a trade.fill and open ${event.toInstrumentId} with its own fill instead.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.contract', eventId: envelope.eventId },
+        });
+    }
+    if (successorTerms.underlyingInstrumentId !== fromTerms.underlyingInstrumentId) {
+        throw new InputError(`${functionName}: derivative.roll event '${envelope.eventId}' changes the underlying from ${fromTerms.underlyingInstrumentId} to ${successorTerms.underlyingInstrumentId} — a roll changes the contract month or strike, not the economic underlying. Close and reopen as separate trade.fill events to change underlyings.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.contract', eventId: envelope.eventId },
+        });
+    }
+    if (fromTerms.kind === 'option' &&
+        successorTerms.kind === 'option' &&
+        successorTerms.type !== fromTerms.type) {
+        throw new InputError(`${functionName}: derivative.roll event '${envelope.eventId}' changes the option type from ${fromTerms.type} to ${successorTerms.type} — a call-to-put (or put-to-call) change is two trades, not a successor-contract roll.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'event.contract', eventId: envelope.eventId },
+        });
+    }
+    requireStyleForTerms(functionName, envelope, event.toInstrumentId, style, successorTerms, 'event.contract');
+    // Close the from-contract: proceeds at the close price for a cash-on-trade position, the
+    // realized difference for a variation-margin one — exactly the closing fill's cash law.
+    const closed = relieveQuantity(functionName, state, envelope, from, q, event.closePricePerUnit, event.lotSelections, 'event.lotSelections');
+    recordRealized(account, event.fromInstrumentId, currency, closed.realizedPnl);
+    finalizePosition(account, from);
+    bookNonZeroCash(account, currency, style === 'cash-on-trade' ? sign * event.closePricePerUnit * q * m : closed.realizedPnl, envelope, undefined);
+    // Open the successor with the same sign and profile.
+    const profile = { currency, contractMultiplier: m, settlementStyle: style };
+    profile.contract = successorTerms;
+    const to = ensurePosition(functionName, account, envelope, event.toInstrumentId, profile, 'event.toInstrumentId');
+    foldPositionLeg(functionName, state, account, envelope, to, sideOf(sign, functionName), q, event.openPricePerUnit, undefined, 'event.lotSelections', `opens ${event.toInstrumentId} and`);
+    if (style === 'cash-on-trade') {
+        bookNonZeroCash(account, currency, -sign * event.openPricePerUnit * q * m, envelope, undefined);
+    }
+}
+// ---------------------------------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------------------------------
+/** Fold one derivative-lifecycle envelope into the working state. */
+export function applyDerivativeEvent(functionName, state, envelope) {
+    const account = accountOf(state, envelope.accountId);
+    const event = envelope.event;
+    switch (event.eventType) {
+        case 'derivative.exercise':
+        case 'derivative.assignment':
+            settleOption(functionName, state, account, envelope, event);
+            return;
+        case 'derivative.expiration':
+            applyExpiration(functionName, state, account, envelope, event);
+            return;
+        case 'derivative.multiplier-change':
+            applyMultiplierChange(functionName, account, envelope, event);
+            return;
+        case 'derivative.variation-margin':
+            applyVariationMargin(functionName, account, envelope, event);
+            return;
+        case 'derivative.roll':
+            applyRoll(functionName, state, account, envelope, event);
+            return;
+        default:
+            throw new InputError(`${functionName}: '${event.eventType}' event '${envelope.eventId}' is not a derivative-lifecycle event — this reducer folds derivative.exercise | derivative.assignment | derivative.expiration | derivative.multiplier-change | derivative.variation-margin | derivative.roll.`, {
+                code: ErrorCode.InputInvalidEnum,
+                context: { function: functionName, field: 'event.eventType', eventId: envelope.eventId },
+            });
+    }
+}
+/**
+ * Undo one applied derivative-lifecycle envelope EXACTLY, or refuse with the reason (through the
+ * kernel's `infeasible`). `applied` is the registry-proven original; `key` its registry identity.
+ * Every family here relieves or re-bases lots and records no effect, so no inverse is provable —
+ * the refusal names the family and the correcting event to record instead.
+ */
+export function reverseDerivativeEvent(functionName, _state, envelope, applied, _key) {
+    const target = applied.event;
+    const settled = (kind) => kind === 'cash' ? 'settled their intrinsic value in cash' : 'delivered the underlying';
+    let detail;
+    switch (target.eventType) {
+        case 'derivative.exercise':
+            detail = `derivative.exercise relieved ${target.quantity} ${target.instrumentId} contracts and ${settled(target.settlement.kind)}; relieved lots cannot be restored exactly. Record the offsetting fills instead.`;
+            break;
+        case 'derivative.assignment':
+            detail = `derivative.assignment covered ${target.quantity} short ${target.instrumentId} contracts and ${settled(target.settlement.kind)}; relieved lots cannot be restored exactly. Record the offsetting fills instead.`;
+            break;
+        case 'derivative.expiration':
+            detail = `derivative.expiration relieved ${target.quantity} ${target.instrumentId} contracts at zero; relieved lots cannot be restored exactly. Record the offsetting fill instead.`;
+            break;
+        case 'derivative.multiplier-change':
+            detail = `derivative.multiplier-change carries only the multiplier after (${target.contractMultiplierAfter}) and the fold does not keep the multiplier before, so the inverse cannot be proven from the fact. Record a derivative.multiplier-change on ${target.instrumentId} back to the prior multiplier instead.`;
+            break;
+        case 'derivative.variation-margin':
+            detail = `derivative.variation-margin re-based every ${target.instrumentId} lot to ${target.settlementPricePerUnit} and realized the difference; the prior bases are not kept. Record a derivative.variation-margin at the correct settlement price instead (the next settlement realizes the difference).`;
+            break;
+        case 'derivative.roll':
+            detail = `derivative.roll relieved ${target.quantity} ${target.fromInstrumentId} and opened ${target.toInstrumentId}; relieved lots cannot be restored exactly. Record the offsetting fills (or a roll back) instead.`;
+            break;
+        default:
+            detail = `'${target.eventType}' is not a derivative-lifecycle event.`;
+    }
+    infeasible(functionName, envelope, detail);
+}
+//# sourceMappingURL=lifecycle-derivatives.js.map

package/modules/portfolio/dist/lifecycle-derivatives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-derivatives.js","sourceRoot":"","sources":["../src/lifecycle-derivatives.ts"],"names":[],"mappings":"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"}

package/modules/portfolio/dist/marks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Valuation marks and the prefix-fold windows behind every "through time" report (slice 2,
+ * 2026-08-28). ONE mark grammar and ONE window builder serve the FC4 seam
+ * (`portfolioPerformanceInputs`), `portfolioPnl`, and `portfolioTimeline`, so the three can never
+ * disagree about which events precede a mark: a mark dated D is the fold of every event with
+ * `effectiveTimestampMs < 00:00 UTC of D`, valued at that instant — the mark lands BEFORE any
+ * same-day flow, exactly FC4's stated flow convention. Package-internal (not an entrypoint).
+ */
+import type { EpochMs } from '../../core/dist/index.js';
+import type { MarketSnapshot } from '../../core/dist/artifacts/index.js';
+import type { PortfolioEventEnvelope } from './events.js';
+import { type CurrencyPairQuote } from './internal.js';
+import type { PortfolioLedger } from './ledger.js';
+import type { PortfolioSnapshotResult } from './snapshot.js';
+import type { PortfolioState } from './state.js';
+/** One dated valuation: the market snapshot (and base-currency quotes) to value the ledger at. */
+export interface PortfolioValuationMark {
+    /** Strict `YYYY-MM-DD`; the mark instant is 00:00 UTC of this date. */
+    valuationDate: string;
+    /** A Gate B market snapshot carrying `observations.spots[instrumentId]` for every held instrument. */
+    market: MarketSnapshot;
+    /** Quotes to the base currency for every non-base cash balance and position currency. */
+    currencyConversions?: CurrencyPairQuote[];
+}
+export declare const MARK_KEYS: readonly ["valuationDate", "market", "currencyConversions"];
+/** Structural validation of a strictly ascending mark list with at least `minimum` entries. */
+export declare function requireValuationMarks(functionName: string, marks: readonly PortfolioValuationMark[], minimum: number, exampleCall: string): void;
+/** The ledger folded up to a mark and valued there, with the events that arrived since the prior mark. */
+export interface MarkWindow {
+    mark: PortfolioValuationMark;
+    /** 00:00 UTC of `mark.valuationDate`. */
+    instant: EpochMs;
+    /** The fold of every event with `effectiveTimestampMs < instant`. */
+    state: PortfolioState;
+    valued: PortfolioSnapshotResult;
+    /** Events with `prior.instant ≤ effectiveTimestampMs < instant` (all events before the first mark, for index 0). */
+    eventsSincePrior: PortfolioEventEnvelope[];
+}
+/**
+ * Fold the ledger incrementally through the marks and value it at each. The caller has already
+ * validated the ledger and the marks; this only sequences them.
+ */
+export declare function foldToMarks(ledger: PortfolioLedger, marks: readonly PortfolioValuationMark[]): MarkWindow[];
+//# sourceMappingURL=marks.d.ts.map

package/modules/portfolio/dist/marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marks.d.ts","sourceRoot":"","sources":["../src/marks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAAoB,CAAC;AASlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,kGAAkG;AAClG,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;IACtB,sGAAsG;IACtG,MAAM,EAAE,cAAc,CAAC;IACvB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC3C;AAED,eAAO,MAAM,SAAS,6DAA8D,CAAC;AAGrF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,IAAI,CAqCN;AAED,0GAA0G;AAC1G,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,sBAAsB,CAAC;IAC7B,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,uBAAuB,CAAC;IAChC,oHAAoH;IACpH,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,SAAS,sBAAsB,EAAE,GACvC,UAAU,EAAE,CAmCd"}

package/modules/portfolio/dist/marks.js

@@ -0,0 +1,81 @@
+/**
+ * Valuation marks and the prefix-fold windows behind every "through time" report (slice 2,
+ * 2026-08-28). ONE mark grammar and ONE window builder serve the FC4 seam
+ * (`portfolioPerformanceInputs`), `portfolioPnl`, and `portfolioTimeline`, so the three can never
+ * disagree about which events precede a mark: a mark dated D is the fold of every event with
+ * `effectiveTimestampMs < 00:00 UTC of D`, valued at that instant — the mark lands BEFORE any
+ * same-day flow, exactly FC4's stated flow convention. Package-internal (not an entrypoint).
+ */
+import { ErrorCode, InputError, ensureKnownKeys, isoDateToEpochMs, requireArgumentArray, requireArgumentObject, } from '../../core/dist/index.js';
+import { describeInputValue } from './internal.js';
+import { portfolioSnapshot } from './snapshot.js';
+import { applyPortfolioEvents } from './state.js';
+export const MARK_KEYS = ['valuationDate', 'market', 'currencyConversions'];
+const STRICT_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Structural validation of a strictly ascending mark list with at least `minimum` entries. */
+export function requireValuationMarks(functionName, marks, minimum, exampleCall) {
+    requireArgumentArray(functionName, 'valuationMarks', marks);
+    if (marks.length < minimum) {
+        throw new InputError(`${functionName}: valuationMarks needs at least ${minimum} dated mark${minimum === 1 ? '' : 's'} — ${minimum >= 2
+            ? 'a change is measured BETWEEN valuations'
+            : 'a report needs one instant to value at'}. Received ${marks.length}.\n  e.g. ${exampleCall}`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'valuationMarks' },
+        });
+    }
+    marks.forEach((mark, index) => {
+        requireArgumentObject(functionName, `valuationMarks[${index}]`, mark);
+        ensureKnownKeys(functionName, `valuationMarks[${index}]`, mark, MARK_KEYS);
+        if (typeof mark.valuationDate !== 'string' || !STRICT_DATE.test(mark.valuationDate)) {
+            throw new InputError(`${functionName}: valuationMarks[${index}].valuationDate must be a strict YYYY-MM-DD calendar date. Received ${describeInputValue(mark.valuationDate)}.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `valuationMarks[${index}].valuationDate` },
+            });
+        }
+        if (index > 0 && mark.valuationDate <= marks[index - 1].valuationDate) {
+            throw new InputError(`${functionName}: valuationMarks must be strictly ascending by valuationDate — [${index - 1}] is ${marks[index - 1].valuationDate} and [${index}] is ${mark.valuationDate}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `valuationMarks[${index}].valuationDate` },
+            });
+        }
+    });
+}
+/**
+ * Fold the ledger incrementally through the marks and value it at each. The caller has already
+ * validated the ledger and the marks; this only sequences them.
+ */
+export function foldToMarks(ledger, marks) {
+    let prefixState = applyPortfolioEvents({
+        portfolio: {
+            ...(ledger.state.portfolioId !== undefined ? { portfolioId: ledger.state.portfolioId } : {}),
+            baseCurrency: ledger.state.baseCurrency,
+            lotRelief: ledger.state.lotRelief,
+        },
+        events: [],
+    });
+    let eventPointer = 0;
+    const windows = [];
+    for (const mark of marks) {
+        const instant = isoDateToEpochMs(mark.valuationDate);
+        const batch = [];
+        while (eventPointer < ledger.events.length &&
+            ledger.events[eventPointer].effectiveTimestampMs < instant) {
+            batch.push(ledger.events[eventPointer]);
+            eventPointer += 1;
+        }
+        if (batch.length > 0) {
+            prefixState = applyPortfolioEvents({ previousState: prefixState, events: batch });
+        }
+        const valued = portfolioSnapshot({
+            portfolio: prefixState,
+            asOf: instant,
+            market: mark.market,
+            ...(mark.currencyConversions !== undefined
+                ? { currencyConversions: mark.currencyConversions }
+                : {}),
+        });
+        windows.push({ mark, instant, state: prefixState, valued, eventsSincePrior: batch });
+    }
+    return windows;
+}
+//# sourceMappingURL=marks.js.map

package/modules/portfolio/dist/marks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marks.js","sourceRoot":"","sources":["../src/marks.ts"],"names":[],"mappings":"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"}