@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/snapshot.js

@@ -0,0 +1,205 @@
+/**
+ * `portfolioSnapshot` — explicit market/as-of valuation of a derived {@link PortfolioState}
+ * (FC7 required API; agent-native Permanent law 2: valuation combines ledger FACTS with an
+ * explicit market snapshot; P&L is a derived report, never ledger state).
+ *
+ * The market is a Gate B `MarketSnapshot` (`@insiderfinance/totalfinance/core/artifacts`) — the platform's ONE
+ * container for "market state at an instant" — validated through `readMarketSnapshot` so there is
+ * exactly one validator. Position marks come from `observations.spots`; base-currency conversion
+ * uses explicit {@link CurrencyPairQuote}s in FC5's vocabulary and arithmetic (see
+ * `internal.ts`). An unavailable mark or quote is a TYPED failure
+ * (`portfolio.mark_unavailable`) — never an interpolation, a stale guess, or a silent skip.
+ *
+ * The settled/unsettled cash split happens HERE, against the explicit `asOf`: the fold records
+ * each dated cash leg; this call classifies legs settling after `asOf` as receivable (incoming)
+ * or payable (outgoing). That keeps the reducer clock-free while the report states
+ * trade-date-vs-settlement-date truth (FC7 mandatory state).
+ */
+import { requireRepresentableResult, CONVENTIONS_VERSION, DataError, ErrorCode, InputError, ensureKnownKeys, requireArgumentArray, requireArgumentObject, resolveAsOf, } from '../../core/dist/index.js';
+import { readMarketSnapshot } from '../../core/dist/artifacts/index.js';
+import { convertWithQuotes, deepFreeze, ownValue, requireCurrencyPairQuoteShape, requireEpochMsField, } from './internal.js';
+import { requirePortfolioStateShape } from './state.js';
+const INPUT_KEYS = ['portfolio', 'asOf', 'market', 'currencyConversions'];
+const VALUATION_CONVENTION = 'Positions mark at observations.spots[instrumentId].price from the supplied market snapshot, ' +
+    'quoted in the position’s trading currency and scaled by the contract multiplier; a ' +
+    'variation-margin position (futures, perpetuals) contributes its unsettled P&L since the last ' +
+    'settlement, not its notional; cash values at face; base-currency conversion uses ' +
+    'the supplied currencyConversions quotes (direct: multiply by quotePerBase; inverted: divide — ' +
+    'FC5 convertCurrency arithmetic). Cash legs with settleTimestampMs > asOf are unsettled: ' +
+    'incoming legs are receivable, outgoing legs payable; settledAmount = totalAmount − ' +
+    'unsettledReceivable + unsettledPayable. Unrealized P&L is marked on open lots only; an ' +
+    'unavailable mark or quote is a typed failure, never a guess.';
+const EXAMPLE_CALL = "portfolioSnapshot({ portfolio: state, asOf: '2026-08-20', market, currencyConversions: [{ baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }] })";
+/**
+ * Value a portfolio state against an explicit market snapshot at an explicit instant.
+ *
+ * @example
+ * ```ts
+ * import { createMarketSnapshot } from '@insiderfinance/totalfinance/core/artifacts';
+ * import { applyPortfolioEvents, portfolioSnapshot } from '@insiderfinance/totalfinance/portfolio';
+ *
+ * const state = applyPortfolioEvents({ portfolio: { baseCurrency: 'USD' }, events });
+ * const market = createMarketSnapshot({
+ *   asOf: '2026-08-20',
+ *   observations: { spots: { AAPL: { price: 232.5, currency: 'USD' } } },
+ * });
+ * const valued = portfolioSnapshot({ portfolio: state, asOf: '2026-08-20', market });
+ * valued.netAssetValue; // cash + positions, in USD
+ * ```
+ */
+export function portfolioSnapshot(input) {
+    const functionName = 'portfolioSnapshot';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, INPUT_KEYS);
+    requirePortfolioStateShape(functionName, 'portfolio', input.portfolio);
+    if (input.asOf === undefined) {
+        throw new InputError(`${functionName}: asOf is required — TotalFinance never reads the system clock, so the caller states the valuation instant.\n  e.g. ${EXAMPLE_CALL}`, { code: ErrorCode.InputMissingField, context: { function: functionName, field: 'asOf' } });
+    }
+    const asOf = resolveAsOf(input.asOf, functionName);
+    requireEpochMsField(functionName, 'asOf', asOf);
+    // ONE validator for market snapshots: the Gate B reader (closed keys, kind, version, finiteness).
+    const { snapshot: market } = readMarketSnapshot({ snapshot: input.market });
+    const quotes = [];
+    if (input.currencyConversions !== undefined) {
+        requireArgumentArray(functionName, 'currencyConversions', input.currencyConversions);
+        input.currencyConversions.forEach((quote, index) => {
+            requireCurrencyPairQuoteShape(functionName, `currencyConversions[${index}]`, quote);
+            quotes.push(quote);
+        });
+    }
+    const warnings = [];
+    if (market.asOf !== asOf) {
+        warnings.push(`${functionName}: the market snapshot is observed at ${market.asOf} but the valuation asOf is ${asOf} — marks from another instant are being applied; supply a snapshot at the valuation instant to remove this warning.`);
+    }
+    const state = input.portfolio;
+    const baseCurrency = state.baseCurrency;
+    const quotesUsed = new Map();
+    const toBase = (amount, currency, subject) => {
+        if (currency === baseCurrency)
+            return amount;
+        const { convertedAmount, quoteUsed } = convertWithQuotes({
+            functionName,
+            amount,
+            fromCurrency: currency,
+            toCurrency: baseCurrency,
+            quotes,
+            subject,
+        });
+        // Echo a COPY — freezing the result must never freeze the caller's own quote objects.
+        quotesUsed.set(`${quoteUsed.baseCurrency}/${quoteUsed.quoteCurrency}`, { ...quoteUsed });
+        return convertedAmount;
+    };
+    const cashRows = [];
+    const positionRows = [];
+    const spots = market.observations.spots ?? {};
+    for (const accountId of Object.keys(state.accounts).sort()) {
+        const account = ownValue(state.accounts, accountId);
+        for (const currency of Object.keys(account.cashBalances).sort()) {
+            const balance = ownValue(account.cashBalances, currency);
+            let unsettledReceivable = 0;
+            let unsettledPayable = 0;
+            for (const leg of balance.settlementSchedule) {
+                if (leg.settleTimestampMs > asOf) {
+                    if (leg.amount > 0)
+                        unsettledReceivable += leg.amount;
+                    else
+                        unsettledPayable += -leg.amount;
+                }
+            }
+            const settledAmount = balance.totalAmount - unsettledReceivable + unsettledPayable;
+            cashRows.push({
+                accountId,
+                currency,
+                totalAmount: balance.totalAmount,
+                settledAmount,
+                unsettledReceivable,
+                unsettledPayable,
+                baseCurrencyValue: toBase(balance.totalAmount, currency, `account '${accountId}' ${currency} cash`),
+            });
+        }
+        for (const instrumentId of Object.keys(account.positions).sort()) {
+            const position = ownValue(account.positions, instrumentId);
+            const spot = ownValue(spots, instrumentId);
+            if (spot === undefined) {
+                throw new DataError(`${functionName}: account '${accountId}' holds ${position.quantity} ${instrumentId}, but the market snapshot carries no observations.spots['${instrumentId}'] — an unavailable mark is a typed failure, never a guess. Add the spot (price + currency) to the snapshot.`, {
+                    code: ErrorCode.PortfolioMarkUnavailable,
+                    context: { function: functionName, accountId, instrumentId },
+                });
+            }
+            if (spot.currency === undefined) {
+                throw new InputError(`${functionName}: observations.spots['${instrumentId}'] states no currency, but it marks a held position — a valuation price must state its currency (${position.currency} here) so nothing is guessed.`, {
+                    code: ErrorCode.InputMissingField,
+                    context: {
+                        function: functionName,
+                        field: `market.observations.spots.${instrumentId}.currency`,
+                    },
+                });
+            }
+            if (spot.currency !== position.currency) {
+                throw new DataError(`${functionName}: observations.spots['${instrumentId}'] is quoted in ${spot.currency}, but account '${accountId}' built the position in ${position.currency} — a mark in another currency is not a mark for these lots. Supply the ${position.currency} price.`, {
+                    code: ErrorCode.PortfolioMarkUnavailable,
+                    context: {
+                        function: functionName,
+                        accountId,
+                        instrumentId,
+                        markCurrency: spot.currency,
+                        positionCurrency: position.currency,
+                    },
+                });
+            }
+            const multiplier = position.contractMultiplier;
+            const notionalValue = position.quantity * spot.price * multiplier;
+            const marketValue = position.settlementStyle === 'variation-margin'
+                ? position.lots.reduce((sum, lot) => sum + (spot.price - lot.costBasisPerUnit) * lot.quantity * multiplier, 0)
+                : notionalValue;
+            const costBasis = position.settlementStyle === 'variation-margin'
+                ? 0
+                : position.lots.reduce((sum, lot) => sum + lot.quantity * lot.costBasisPerUnit * multiplier, 0);
+            const unrealizedPnl = marketValue - costBasis;
+            const baseCurrencyNotionalValue = toBase(notionalValue, position.currency, `account '${accountId}' ${instrumentId} notional`);
+            const baseCurrencyMarketValue = toBase(marketValue, position.currency, `account '${accountId}' ${instrumentId} position`);
+            const baseCurrencyUnrealizedPnl = toBase(unrealizedPnl, position.currency, `account '${accountId}' ${instrumentId} unrealized P&L`);
+            positionRows.push({
+                accountId,
+                instrumentId,
+                currency: position.currency,
+                quantity: position.quantity,
+                markPricePerUnit: spot.price,
+                contractMultiplier: multiplier,
+                settlementStyle: position.settlementStyle,
+                marketValue,
+                baseCurrencyMarketValue,
+                notionalValue,
+                baseCurrencyNotionalValue,
+                costBasis,
+                unrealizedPnl,
+                baseCurrencyUnrealizedPnl,
+                lotCount: position.lots.length,
+            });
+        }
+    }
+    const totalCashBaseCurrencyValue = cashRows.reduce((sum, row) => sum + row.baseCurrencyValue, 0);
+    const totalPositionsBaseCurrencyValue = positionRows.reduce((sum, row) => sum + row.baseCurrencyMarketValue, 0);
+    return deepFreeze(requireRepresentableResult('portfolioSnapshot', {
+        asOf,
+        baseCurrency,
+        netAssetValue: totalCashBaseCurrencyValue + totalPositionsBaseCurrencyValue,
+        cash: cashRows,
+        totalCashBaseCurrencyValue,
+        positions: positionRows,
+        totalPositionsBaseCurrencyValue,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            lotRelief: state.lotRelief,
+            marketAsOf: market.asOf,
+            currencyConversionsUsed: [...quotesUsed.keys()].sort().map((key) => quotesUsed.get(key)),
+            valuationConvention: VALUATION_CONVENTION,
+        },
+        diagnostics: {
+            warnings,
+            accountCount: Object.keys(state.accounts).length,
+            positionCount: positionRows.length,
+        },
+    }));
+}
+//# sourceMappingURL=snapshot.js.map

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

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

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

@@ -0,0 +1,196 @@
+/**
+ * The FC7 pure reducer: `PortfolioState` is a FOLD over immutable economic events (agent-native
+ * platform doc, Permanent law 1 — "Portfolio truth is event-derived"; spec D16). Same events →
+ * same state, always: the fold reads no clock, no locale, no global registry, and never mutates
+ * its inputs. Replaying an identical `(sourceId, eventId)` envelope is a no-op; a same-key
+ * envelope with a different body is a typed conflict (`portfolio.duplicate_event_conflict`).
+ *
+ * The fold derives FACTS ONLY: cash by currency (with each leg's settlement schedule — the
+ * settled/unsettled SPLIT is classified at an explicit `asOf` by `portfolioSnapshot`, keeping the
+ * fold clock-free), positions with signed fractional tax lots, realized P&L from lot relief, and
+ * income/cost/financing accumulators. Unrealized P&L, NAV, and base-currency values need marks
+ * and are derived reports (Permanent law 2 — "P&L is a derived result, not a ledger event").
+ */
+import type { EpochMs } from '../../core/dist/index.js';
+import type { DerivativeContractTerms, PortfolioEventEnvelope, SettlementStyle } from './events.js';
+export { reliefOrder } from './reducer-kernel.js';
+import type { PortfolioLedger } from './ledger.js';
+/** The decided lot-relief set (agent-native doc, "Initial accounting scope"). */
+export type LotReliefPolicy = 'fifo' | 'lifo' | 'highest-cost' | 'specific-lot';
+/** One dated cash leg: `amount` (signed) becomes settled once `asOf ≥ settleTimestampMs`. */
+export interface ScheduledSettlement {
+    /** The envelope `eventId` that booked this leg. */
+    eventId: string;
+    /** Signed cash effect: positive = incoming (receivable until settled), negative = payable. */
+    amount: number;
+    settleTimestampMs: EpochMs;
+}
+/** One currency's cash: the booked total plus the settlement schedule of its dated legs. */
+export interface CashBalance {
+    /** The booked balance including not-yet-settled legs. May be negative (margin/overdraft). */
+    totalAmount: number;
+    settlementSchedule: ScheduledSettlement[];
+}
+/** One tax lot. Long lots have `quantity > 0`; short lots `quantity < 0`. */
+export interface TaxLot {
+    /** Deterministic fold identity (`lot-<n>`), stable across replays — addressable by
+     * `specific-lot` relief. */
+    lotId: string;
+    openedByEventId: string;
+    openedTimestampMs: EpochMs;
+    /** Signed remaining quantity; fractional supported. */
+    quantity: number;
+    /** For long lots: acquisition price per unit. For short lots: opening proceeds per unit. */
+    costBasisPerUnit: number;
+}
+/** One instrument's open position in one account. */
+export interface PositionState {
+    instrumentId: string;
+    /** The ONE trading currency of this position's fills (mixed currencies refuse). */
+    currency: string;
+    /** Units of the underlying per unit of `quantity` (slice 5): 1 for shares, an option's 100, a futures contract size. */
+    contractMultiplier: number;
+    /** `'cash-on-trade'` (equities, options, spot) or `'variation-margin'` (futures, perpetuals). */
+    settlementStyle: SettlementStyle;
+    /** The derivative's terms, carried from the opening fill. */
+    contract?: DerivativeContractTerms;
+    /** Signed net quantity — always the sum of `lots[].quantity`. */
+    quantity: number;
+    lots: TaxLot[];
+}
+/** One account's derived facts. Accumulators are keyed by uppercase currency code. */
+export interface AccountState {
+    cashBalances: Record<string, CashBalance>;
+    positions: Record<string, PositionState>;
+    /** Realized P&L from lot relief under the state's `lotRelief` policy, by currency. */
+    realizedPnl: Record<string, number>;
+    /** Income received (dividends, coupons, interest, staking, funding receipts), by currency. */
+    incomeReceived: Record<string, number>;
+    /** Transaction costs charged (commissions, fees, slippage adjustments), by currency. */
+    transactionCosts: Record<string, number>;
+    /** Financing charged (margin interest, borrow, funding payments), by currency. */
+    financingCosts: Record<string, number>;
+    /**
+     * Per-instrument attribution of the realized, income, and cost accumulators (slice 2,
+     * 2026-08-28): `instrumentId → currency → amount`. Realized P&L always carries the instrument;
+     * income and costs carry it only when the event named one (unattributed amounts stay in the
+     * account-level totals above and are reported as such by `portfolioPnl`). These survive a
+     * position closing — `positions` drops a flat instrument, its history does not disappear.
+     */
+    realizedPnlByInstrument: Record<string, Record<string, number>>;
+    incomeByInstrument: Record<string, Record<string, number>>;
+    transactionCostsByInstrument: Record<string, Record<string, number>>;
+}
+/**
+ * 2 (2026-08-28, FC7 slice 2): accounts gained the per-instrument attribution maps.
+ * 3 (2026-08-28, FC7 slice 3): the fold records per-fill effects (for exact reversal), the
+ * reversal links, and account-migration markers.
+ * 4 (2026-08-29, FC7 slice 5): positions carry their instrument profile (contract multiplier,
+ * settlement style, derivative terms) and fill effects record the cash they booked.
+ */
+export declare const PORTFOLIO_STATE_SCHEMA_VERSION = 4;
+/** What one applied fill did — the facts an exact reversal needs (slice 3). */
+export interface FillEffect {
+    accountId: string;
+    instrumentId: string;
+    currency: string;
+    /** Lot ids this fill OPENED (in order). Empty when the fill only relieved. */
+    openedLotIds: string[];
+    /** Quantity this fill relieved from prior lots — non-zero means the fill is not exactly reversible. */
+    relievedQuantity: number;
+    realizedPnl: number;
+    /** The signed cash the fill booked (price × quantity × multiplier, or the realized variation-margin P&L), incl. accrued interest. */
+    cashDelta: number;
+    /** Signed accrued interest exchanged (negative = paid on a buy), booked as income. */
+    accruedInterest: number;
+}
+/** An account-migration marker as folded (slice 3): the fact IS the marker; no economic effect. */
+export interface AccountMigrationMarker {
+    eventId: string;
+    fromAccountId: string;
+    toAccountId: string;
+    effectiveTimestampMs: EpochMs;
+}
+/**
+ * The derived portfolio state: a JSON-safe, deeply frozen fold result. The economic policy that
+ * shaped it (`baseCurrency`, `lotRelief`) is echoed ON the state, and the applied-event registry
+ * makes replay idempotent and conflict-detecting.
+ */
+export interface PortfolioState {
+    schemaVersion: number;
+    portfolioId?: string;
+    baseCurrency: string;
+    /** The lot-relief policy every realized figure in this state was computed under. */
+    lotRelief: LotReliefPolicy;
+    accounts: Record<string, AccountState>;
+    /** `(sourceId, eventId)` → event content hash — the duplicate/conflict boundary. */
+    appliedEvents: Record<string, string>;
+    eventCount: number;
+    lastEffectiveTimestampMs: EpochMs | null;
+    /** Fold-deterministic lot-id counter (`lot-<n>`). */
+    lotSequence: number;
+    /** Registry key of every applied `trade.fill` → what it did (slice 3; exact reversal needs it). */
+    fillEffects: Record<string, FillEffect>;
+    /** Registry key of every reversed fact → registry key of the admin event that reversed it. */
+    reversals: Record<string, string>;
+    /** Account-migration markers in fold order. */
+    accountMigrations: AccountMigrationMarker[];
+}
+/** The fresh-ledger definition accepted by {@link applyPortfolioEvents} and the ledger artifact. */
+export interface PortfolioDefinition {
+    portfolioId?: string;
+    baseCurrency: string;
+    /** Defaults to `'fifo'` (documented; echoed on the state and every ledger envelope). */
+    lotRelief?: LotReliefPolicy;
+}
+/** Input for {@link applyPortfolioEvents}: exactly ONE of `portfolio` (fresh) or `previousState`. */
+export interface ApplyPortfolioEventsInput {
+    portfolio?: PortfolioDefinition;
+    previousState?: PortfolioState;
+    events: readonly PortfolioEventEnvelope[];
+}
+/**
+ * Deep validation of a {@link PortfolioState} handed back across a public boundary
+ * (`applyPortfolioEvents`' `previousState`, `portfolioSnapshot`'s `portfolio`). A TypeScript type
+ * does not survive storage or network transit, so every nested account, cash leg, position, lot,
+ * attribution, effect, reversal, migration, and registry link is re-audited before use.
+ * Package-internal (imported by the snapshot module); not part of the curated public surface.
+ */
+export declare function requirePortfolioStateShape(functionName: string, label: string, state: PortfolioState): void;
+/**
+ * The direct pure reducer (FC7 required API; the agent-native doc's decided API ladder): fold
+ * `events` over a fresh `portfolio` definition or a `previousState`, returning a new deeply
+ * frozen {@link PortfolioState}.
+ *
+ * Laws (tested in `test/apply.test.ts`):
+ *
+ * - **replay determinism** — same events, same order → deep-equal state;
+ * - **duplicate idempotence** — an already-applied `(sourceId, eventId)` with an identical body
+ *   (content hash, provenance excluded) is a no-op;
+ * - **conflict detection** — a same-key body change throws `portfolio.duplicate_event_conflict`;
+ * - **ordering** — events fold in array order and must be non-decreasing in
+ *   `effectiveTimestampMs` (ties keep array order);
+ * - **immutability** — neither `previousState` nor any envelope is mutated; the result owns its
+ *   own frozen tree.
+ *
+ * @example
+ * ```ts
+ * import { applyPortfolioEvents } from '@insiderfinance/totalfinance/portfolio';
+ *
+ * const state = applyPortfolioEvents({ portfolio: { baseCurrency: 'USD' }, events });
+ * const next = applyPortfolioEvents({ previousState: state, events: moreEvents });
+ * ```
+ */
+export declare function applyPortfolioEvents(input: ApplyPortfolioEventsInput): PortfolioState;
+/**
+ * Structural validation of a {@link PortfolioLedger} handed back across a public boundary (the
+ * performance seam). A ledger is a VALUE object: it can be spread, cloned, or hand-assembled after
+ * creation, so every door re-validates it — closed keys, both methods present, every event through
+ * the closed envelope validator, the state through its own validator, and the top-level echoes
+ * (`baseCurrency`, `lotRelief`, `portfolioId`) equal to the state they summarize. The enforcement
+ * harness (2026-08-28) reached the seam with `apply` missing and `baseCurrency: null` and was
+ * answered with a series. Package-internal (state.ts is not an entrypoint); not part of the curated public surface — a
+ * public `require*` leak is exactly what the review waves evicted elsewhere.
+ */
+export declare function requirePortfolioLedger(functionName: string, label: string, ledger: PortfolioLedger): void;
+//# sourceMappingURL=state.d.ts.map

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

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