@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/rebalance.js

@@ -0,0 +1,1236 @@
+/**
+ * `proposePortfolioRebalance` (FC7 slice 4, Stage 4.4; agent-native "Rebalance proposal"): a pure,
+ * contribution/withdrawal-aware PROPOSAL over an event-derived ledger valued against an explicit
+ * market snapshot. It produces a plan and never executes it.
+ *
+ * Laws this module executes (agent-native doc → "Rebalance proposal"; tracker → "Portfolio-side
+ * management"):
+ *
+ * - **A proposal is a plan.** The result carries trades, estimates, and a normalized,
+ *   content-addressed `TradePlanArtifact` suitable for preflight — and no execution capability.
+ * - **Hard constraints are never silently relaxed.** A turnover cap or cash floor that binds trims
+ *   the plan and is reported as a `capped` constraint (the GOAL is unmet, the CONSTRAINT holds); a
+ *   post-trade limit the plan would break is reported as `violated` with the number and the plan
+ *   is `feasible: false` — the trades stay listed so the caller sees what the targets ask for.
+ * - **New cash first.** A contribution invested to targets funds underweights before anything is
+ *   sold; sizing over the post-flow NAV makes that the natural to-target plan.
+ * - **Everything explicit.** Infeasibility, non-convergence, skipped dust, rounding, residual cash,
+ *   unavailable liquidity data, and the lot-selection preview's availability under the ledger's
+ *   own relief policy are all reported; missing goals (a flow with no handling, a scope) are typed
+ *   refusals, never defaults.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, isOccOptionSymbol, requireArgumentObject, requireRepresentableResult, resolveAsOf, sideOf, } from '../../core/dist/index.js';
+import { contentHash, readMarketSnapshot } from '../../core/dist/artifacts/index.js';
+import { allocatePortfolio, describeCostModel, describeRounding, estimateTradeCost, lotSizeFor, requireAllocationSizing, roundTowardZeroToLot, sortUnresolved, } from './allocation.js';
+import { QUANTITY_DUST, convertWithQuotes, deepFreeze, describeInputValue, ownValue, requireCurrencyCode, requireEpochMsField, requireFiniteNumberField, requireIdentityString, requirePositiveNumberField, setOwnValue, } from './internal.js';
+import { requireInstrumentClassification } from './pnl.js';
+import { CASH_ASSET_CLASS, expandTargets, instrumentGroupKeys, isCashTargetGroup, requireInvestmentPolicy, resolvePolicyTargets, targetGroupKey, } from './policy-grammar.js';
+import { portfolioSnapshot } from './snapshot.js';
+import { reliefOrder, requirePortfolioStateShape } from './state.js';
+export const TRADE_PLAN_KIND = 'totalfinance.trade-plan';
+export const TRADE_PLAN_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------------------------------
+const INPUT_KEYS = [
+    'portfolio',
+    'market',
+    'asOf',
+    'currencyConversions',
+    'policy',
+    'instrumentClassification',
+    'scope',
+    'externalFlow',
+    'tradingAccountId',
+    'lotSizes',
+    'defaultLotSize',
+    'minimumNotional',
+    'transactionCosts',
+    'averageDailyVolumes',
+];
+const FLOW_KEYS = ['amount', 'currency'];
+const SCOPES = ['to-target', 'drift-only'];
+/** Liquidity horizon: days = |quantity| ÷ (average daily volume × this participation rate). */
+const LIQUIDITY_PARTICIPATION_RATE = 0.1;
+const MAXIMUM_ITERATIONS = 3;
+const AMOUNT_TOLERANCE_FRACTION = 1e-9;
+const WEIGHT_NOISE = 1e-12;
+const CONVENTIONS = 'The managed book is the policy’s allowed accounts (all accounts when none are declared); ' +
+    'holdings in other accounts are reported and never traded. Weights are of the managed NAV at ' +
+    'the snapshot marks (before) and of the post-flow NAV after the proposed trades (after); trades ' +
+    'are value-neutral at the mark and estimated costs are never deducted from cash. Drift is ' +
+    'current − target; a target is outside its band when |drift| > band. In scope ‘drift-only’ a ' +
+    'trade is kept when its instrument or one of its source groups is outside its band; in ' +
+    '‘to-target’ every instrument moves to target. Sizing is one allocatePortfolio pass over the ' +
+    'post-flow NAV (the pre-flow NAV when a contribution is held as cash) with the ledger’s ' +
+    'holdings and marks; the turnover cap scales every kept trade by cap ÷ required and the cash ' +
+    'floor scales buys by available ÷ needed, each re-rounded toward zero to the lot size on the ' +
+    'trade quantity, at most three passes. Buys book to the trading account; a trade that closes ' +
+    'a position books to the holding account(s) in accountId order and previews the lots the ' +
+    'ledger’s own lotRelief policy would relieve at the mark. Post-trade limits are evaluated, ' +
+    'never auto-fixed. maximumDrawdown and maximumDailyLoss need a history and are evaluated by ' +
+    'monitorPortfolio, not here. driftDistance = Σ|weight − target| ÷ 2 over instrument targets ' +
+    'and cash; trackingDistance is the active share vs the benchmark constituents (cash counts ' +
+    'as an asset the benchmark does not hold); herfindahlIndex = Σ weight² over instruments.';
+const EXAMPLE_CALL = "proposePortfolioRebalance({ portfolio: ledger.state, market, asOf: '2026-08-29', scope: 'drift-only', policy: { targets: [{ group: { tag: 'equity' }, weight: 0.6 }, { group: { tag: 'fixed-income' }, weight: 0.3 }, { group: { assetClass: 'cash' }, weight: 0.1 }], driftBand: 0.03, maximumTurnover: 0.15, minimumCash: 5_000 }, instrumentClassification: { SPY: { tags: ['equity'] }, AGG: { tags: ['fixed-income'] } }, defaultLotSize: 1 })";
+// ---------------------------------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------------------------------
+function requireScope(functionName, value) {
+    if (value === undefined) {
+        throw new InputError(`${functionName}: scope is required — 'to-target' trades every instrument to its target; 'drift-only' trades only instruments (or groups) outside their drift band. Which one is a goal, not a default.\n  e.g. ${EXAMPLE_CALL}`, { code: ErrorCode.InputMissingField, context: { function: functionName, field: 'scope' } });
+    }
+    if (typeof value !== 'string' || !SCOPES.includes(value)) {
+        throw new InputError(`${functionName}: scope must be 'to-target' or 'drift-only'. Received ${describeInputValue(value)}.`, {
+            code: typeof value === 'string' ? ErrorCode.InputOutOfRange : ErrorCode.InputWrongType,
+            context: { function: functionName, field: 'scope' },
+        });
+    }
+    return value;
+}
+function requireExternalFlow(functionName, value, baseCurrency) {
+    if (value === undefined)
+        return null;
+    requireArgumentObject(functionName, 'externalFlow', value);
+    ensureKnownKeys(functionName, 'externalFlow', value, FLOW_KEYS);
+    const raw = value;
+    requireFiniteNumberField(functionName, 'externalFlow.amount', raw['amount']);
+    if (raw['amount'] === 0) {
+        throw new InputError(`${functionName}: externalFlow.amount must be non-zero (> 0 a contribution, < 0 a withdrawal) — omit externalFlow when no flow is planned.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'externalFlow.amount' },
+        });
+    }
+    requireCurrencyCode(functionName, 'externalFlow.currency', raw['currency']);
+    if (raw['currency'] !== baseCurrency) {
+        throw new InputError(`${functionName}: externalFlow is stated in ${raw['currency']}, but the portfolio's base currency is ${baseCurrency} — this build sizes flows in the base currency only (a foreign-currency flow is deferred: record its cash.deposit and cash.conversion events first, or state the amount in ${baseCurrency}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'externalFlow.currency' },
+        });
+    }
+    return { amount: raw['amount'], currency: raw['currency'] };
+}
+function requireVolumes(functionName, value) {
+    if (value === undefined)
+        return {};
+    requireArgumentObject(functionName, 'averageDailyVolumes', value);
+    const map = value;
+    const out = {};
+    for (const instrumentId of Object.keys(map).sort()) {
+        requireIdentityString(functionName, 'averageDailyVolumes key', instrumentId);
+        const volume = ownValue(map, instrumentId);
+        requirePositiveNumberField(functionName, `averageDailyVolumes['${instrumentId}']`, volume, 'an average daily volume in units per day');
+        setOwnValue(out, instrumentId, volume);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------------------------------
+function compareIds(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function sleeveLeafMembers(sleeveId, sleeves) {
+    const sleeve = sleeves.find((s) => s.sleeveId === sleeveId);
+    if (sleeve === undefined)
+        return [];
+    if (sleeve.members !== undefined)
+        return sleeve.members.map((m) => m.instrumentId);
+    const out = new Set();
+    for (const child of sleeves.filter((s) => s.parentSleeveId === sleeveId)) {
+        for (const id of sleeveLeafMembers(child.sleeveId, sleeves))
+            out.add(id);
+    }
+    return [...out].sort();
+}
+function riskPoint(weights, cashWeight) {
+    const magnitudes = [...weights.values()].map((w) => Math.abs(w)).sort((a, b) => b - a);
+    let herfindahl = 0;
+    for (const w of weights.values())
+        herfindahl += w * w;
+    return {
+        maximumPositionWeight: magnitudes[0] ?? 0,
+        herfindahlIndex: herfindahl,
+        topThreeWeight: magnitudes.slice(0, 3).reduce((sum, w) => sum + w, 0),
+        grossLeverage: magnitudes.reduce((sum, w) => sum + w, 0),
+        cashWeight,
+    };
+}
+function previewLots(position, quantity, lotRelief) {
+    const lots = [];
+    let remaining = quantity;
+    let realized = 0;
+    for (const lot of reliefOrder(position.lots, lotRelief)) {
+        if (remaining <= QUANTITY_DUST)
+            break;
+        const take = Math.min(Math.abs(lot.quantity), remaining);
+        const estimatedRealizedPnl = lot.quantity > 0
+            ? (position.markPricePerUnit - lot.costBasisPerUnit) * take
+            : (lot.costBasisPerUnit - position.markPricePerUnit) * take;
+        lots.push({
+            lotId: lot.lotId,
+            quantity: take,
+            costBasisPerUnit: lot.costBasisPerUnit,
+            estimatedRealizedPnl,
+        });
+        realized += estimatedRealizedPnl;
+        remaining -= take;
+    }
+    return { policy: lotRelief, lots, estimatedRealizedPnl: realized };
+}
+// ---------------------------------------------------------------------------------------------------
+// The head
+// ---------------------------------------------------------------------------------------------------
+/**
+ * Propose a rebalance of the ledger's managed book toward the policy's targets at `asOf` — a plan,
+ * never an execution. See the module comment for the laws and the accepted example.
+ *
+ * @example
+ * ```ts
+ * import { createMarketSnapshot } from '@insiderfinance/totalfinance/core/artifacts';
+ * import { proposePortfolioRebalance } from '@insiderfinance/totalfinance/portfolio/policy';
+ *
+ * const proposal = proposePortfolioRebalance({
+ *   portfolio: ledger.state,
+ *   market: createMarketSnapshot({ asOf: '2026-08-29', observations: { spots: { SPY: { price: 120, currency: 'USD' }, AGG: { price: 100, currency: 'USD' } } } }),
+ *   asOf: '2026-08-29',
+ *   scope: 'drift-only',
+ *   policy: {
+ *     targets: [
+ *       { group: { tag: 'equity' }, weight: 0.6 },
+ *       { group: { tag: 'fixed-income' }, weight: 0.3 },
+ *       { group: { assetClass: 'cash' }, weight: 0.1 },
+ *     ],
+ *     driftBand: 0.03,
+ *     maximumTurnover: 0.15,
+ *     minimumCash: 5_000,
+ *   },
+ *   instrumentClassification: { SPY: { tags: ['equity'] }, AGG: { tags: ['fixed-income'] } },
+ *   defaultLotSize: 1,
+ * });
+ * proposal.trades; // sell SPY, buy AGG — only what is outside the 3% band
+ * proposal.plan.contentHash; // 'sha256:…' — a normalized plan for preflight
+ * ```
+ */
+export function proposePortfolioRebalance(input) {
+    const functionName = 'proposePortfolioRebalance';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, INPUT_KEYS);
+    requirePortfolioStateShape(functionName, 'portfolio', input.portfolio);
+    const state = input.portfolio;
+    const baseCurrency = state.baseCurrency;
+    if (input.asOf === undefined) {
+        throw new InputError(`${functionName}: asOf is required — the book is valued and the targets resolve at an explicit instant; TotalFinance never reads the system clock.\n  e.g. ${EXAMPLE_CALL}`, { code: ErrorCode.InputMissingField, context: { function: functionName, field: 'asOf' } });
+    }
+    const asOf = resolveAsOf(input.asOf, functionName);
+    requireEpochMsField(functionName, 'asOf', asOf);
+    if (input.policy === undefined) {
+        throw new InputError(`${functionName}: policy is required — the targets, bands, and limits are the caller's goals.\n  e.g. ${EXAMPLE_CALL}`, { code: ErrorCode.InputMissingField, context: { function: functionName, field: 'policy' } });
+    }
+    const policy = requireInvestmentPolicy(functionName, 'policy', input.policy);
+    if (policy.model !== undefined && policy.model.baseCurrency !== baseCurrency) {
+        throw new InputError(`${functionName}: policy.model '${policy.model.modelId}' v${policy.model.version} is stated in ${policy.model.baseCurrency}, but the portfolio's base currency is ${baseCurrency} — a model's weights are shares of a NAV in its own currency.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'policy.model.baseCurrency' },
+        });
+    }
+    const scope = requireScope(functionName, input.scope);
+    const flow = requireExternalFlow(functionName, input.externalFlow, baseCurrency);
+    if (input.tradingAccountId !== undefined) {
+        requireIdentityString(functionName, 'tradingAccountId', input.tradingAccountId);
+    }
+    const sizing = requireAllocationSizing(functionName, input);
+    const volumes = requireVolumes(functionName, input.averageDailyVolumes);
+    const classification = requireInstrumentClassification(functionName, input.instrumentClassification);
+    // Flow handling is a goal: a flow without its handling is a typed refusal.
+    const flowAmount = flow?.amount ?? 0;
+    if (flowAmount > 0 && policy.contributionHandling === undefined) {
+        throw new InputError(`${functionName}: externalFlow plans a contribution of ${flowAmount} ${baseCurrency}, but the policy declares no contributionHandling ('invest-to-targets' spends it on underweights first; 'hold-as-cash' leaves it in cash) — how new cash is treated is a goal, not a default.`, {
+            code: ErrorCode.InputMissingField,
+            context: { function: functionName, field: 'policy.contributionHandling' },
+        });
+    }
+    if (flowAmount < 0 && policy.withdrawalHandling === undefined) {
+        throw new InputError(`${functionName}: externalFlow plans a withdrawal of ${-flowAmount} ${baseCurrency}, but the policy declares no withdrawalHandling ('raise-from-overweights' sells the most overweight holdings first; 'pro-rata' sells every holding proportionally) — how cash is raised is a goal, not a default.`, {
+            code: ErrorCode.InputMissingField,
+            context: { function: functionName, field: 'policy.withdrawalHandling' },
+        });
+    }
+    // ---- valuation: ONE market validator, ONE valuation law ----
+    const { snapshot: market } = readMarketSnapshot({ snapshot: input.market });
+    const valued = portfolioSnapshot({
+        portfolio: state,
+        asOf,
+        market: input.market,
+        ...(input.currencyConversions !== undefined
+            ? { currencyConversions: input.currencyConversions }
+            : {}),
+    });
+    const warnings = [...valued.diagnostics.warnings];
+    const quotes = input.currencyConversions ?? [];
+    const toBase = (amount, currency, subject) => currency === baseCurrency
+        ? amount
+        : convertWithQuotes({
+            functionName,
+            amount,
+            fromCurrency: currency,
+            toCurrency: baseCurrency,
+            quotes,
+            subject,
+        }).convertedAmount;
+    // ---- accounts: the managed book ----
+    const allAccounts = Object.keys(state.accounts).sort();
+    let accountsConsidered = allAccounts;
+    let accountsExcluded = [];
+    if (policy.allowedAccounts !== undefined) {
+        const allowedSet = new Set(policy.allowedAccounts);
+        accountsConsidered = allAccounts.filter((id) => allowedSet.has(id));
+        accountsExcluded = allAccounts.filter((id) => !allowedSet.has(id));
+        const unknown = policy.allowedAccounts.filter((id) => ownValue(state.accounts, id) === undefined);
+        if (unknown.length > 0) {
+            warnings.push(`policy.allowedAccounts names ${unknown.map((id) => `'${id}'`).join(', ')}, which the portfolio has no state for — nothing is booked there.`);
+        }
+    }
+    if (accountsConsidered.length === 0) {
+        throw new InputError(`${functionName}: policy.allowedAccounts (${(policy.allowedAccounts ?? []).join(', ') || 'none'}) matches no account in the portfolio (accounts: ${allAccounts.join(', ') || 'none'}) — there is no managed book to rebalance.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'policy.allowedAccounts' },
+        });
+    }
+    const consideredSet = new Set(accountsConsidered);
+    let tradingAccountId;
+    if (accountsConsidered.length === 1) {
+        tradingAccountId = accountsConsidered[0];
+        if (input.tradingAccountId !== undefined && input.tradingAccountId !== tradingAccountId) {
+            throw new InputError(`${functionName}: tradingAccountId '${input.tradingAccountId}' is not the managed account ('${tradingAccountId}') — buys book to an allowed account.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: 'tradingAccountId' },
+            });
+        }
+    }
+    else {
+        if (input.tradingAccountId === undefined) {
+            throw new InputError(`${functionName}: tradingAccountId is required — the managed book spans ${accountsConsidered.length} accounts (${accountsConsidered.join(', ')}), and where BUYS book is a decision, not a default. Sells book to the account(s) holding the position.`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field: 'tradingAccountId' },
+            });
+        }
+        if (!consideredSet.has(input.tradingAccountId)) {
+            throw new InputError(`${functionName}: tradingAccountId '${input.tradingAccountId}' is not one of the managed accounts (${accountsConsidered.join(', ')}).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: 'tradingAccountId' },
+            });
+        }
+        tradingAccountId = input.tradingAccountId;
+    }
+    // ---- holdings, marks, and cash over the managed book ----
+    const positionsByInstrument = new Map();
+    const heldQuantity = {};
+    const heldValueBase = new Map();
+    const prices = {};
+    const contractMultipliers = {};
+    let managedPositionsValue = 0;
+    for (const row of valued.positions) {
+        if (!consideredSet.has(row.accountId))
+            continue;
+        const list = positionsByInstrument.get(row.instrumentId) ?? [];
+        list.push({
+            accountId: row.accountId,
+            quantity: row.quantity,
+            currency: row.currency,
+            markPricePerUnit: row.markPricePerUnit,
+            lots: ownValue(ownValue(state.accounts, row.accountId).positions, row.instrumentId).lots,
+        });
+        positionsByInstrument.set(row.instrumentId, list);
+        setOwnValue(heldQuantity, row.instrumentId, (ownValue(heldQuantity, row.instrumentId) ?? 0) + row.quantity);
+        // Weights and sizing use NOTIONAL (quantity × mark × multiplier); NAV uses market value.
+        heldValueBase.set(row.instrumentId, (heldValueBase.get(row.instrumentId) ?? 0) + row.baseCurrencyNotionalValue);
+        managedPositionsValue += row.baseCurrencyMarketValue;
+        setOwnValue(contractMultipliers, row.instrumentId, row.contractMultiplier);
+        setOwnValue(prices, row.instrumentId, {
+            price: row.markPricePerUnit,
+            currency: row.currency,
+        });
+    }
+    let totalCashBase = 0;
+    let settledCashBase = 0;
+    const settledByAccount = new Map();
+    for (const row of valued.cash) {
+        if (!consideredSet.has(row.accountId))
+            continue;
+        totalCashBase += row.baseCurrencyValue;
+        const settled = toBase(row.settledAmount, row.currency, `account '${row.accountId}' settled ${row.currency} cash`);
+        settledCashBase += settled;
+        settledByAccount.set(row.accountId, (settledByAccount.get(row.accountId) ?? 0) + settled);
+    }
+    const netAssetValue = totalCashBase + managedPositionsValue;
+    if (accountsExcluded.length > 0) {
+        const excludedValue = valued.cash
+            .filter((row) => !consideredSet.has(row.accountId))
+            .reduce((sum, row) => sum + row.baseCurrencyValue, 0) +
+            valued.positions
+                .filter((row) => !consideredSet.has(row.accountId))
+                .reduce((sum, row) => sum + row.baseCurrencyMarketValue, 0);
+        const excludedHoldings = valued.positions
+            .filter((row) => !consideredSet.has(row.accountId))
+            .map((row) => `${row.quantity} ${row.instrumentId} in '${row.accountId}'`);
+        warnings.push(`${accountsExcluded.length} account${accountsExcluded.length === 1 ? '' : 's'} outside policy.allowedAccounts (${accountsExcluded.join(', ')}) hold ${excludedValue} ${baseCurrency}${excludedHoldings.length > 0 ? ` (${excludedHoldings.join('; ')})` : ''} — excluded from the managed NAV and never traded.`);
+    }
+    if (!(netAssetValue > 0)) {
+        throw new InputError(`${functionName}: the managed net asset value is ${netAssetValue} ${baseCurrency} (accounts ${accountsConsidered.join(', ')}) — weights need a positive NAV; deposit cash or widen policy.allowedAccounts.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'portfolio' },
+        });
+    }
+    const tolerance = netAssetValue * AMOUNT_TOLERANCE_FRACTION;
+    // ---- the universe and the policy's lists ----
+    const resolved = resolvePolicyTargets(functionName, policy, asOf);
+    const sleeves = policy.model?.sleeves ?? [];
+    const restricted = new Set(policy.restrictedInstruments ?? []);
+    const allowedInstruments = policy.allowedInstruments === undefined ? null : new Set(policy.allowedInstruments);
+    const universeAll = new Set(Object.keys(heldQuantity));
+    for (const id of policy.allowedInstruments ?? [])
+        universeAll.add(id);
+    for (const target of resolved.targets) {
+        if (target.group.instrumentId !== undefined)
+            universeAll.add(target.group.instrumentId);
+    }
+    for (const sleeve of sleeves)
+        for (const member of sleeve.members ?? [])
+            universeAll.add(member.instrumentId);
+    const unresolvedTargets = [];
+    const restrictedHeld = new Set();
+    const disallowedHeld = new Set();
+    for (const id of Object.keys(heldQuantity)) {
+        if (restricted.has(id))
+            restrictedHeld.add(id);
+        else if (allowedInstruments !== null && !allowedInstruments.has(id))
+            disallowedHeld.add(id);
+    }
+    const expansionUniverse = [...universeAll].filter((id) => !restricted.has(id) && !disallowedHeld.has(id));
+    // Spots for universe instruments not held (a trade into a new name needs a priced currency).
+    const spots = market.observations.spots ?? {};
+    for (const id of expansionUniverse) {
+        if (ownValue(prices, id) !== undefined)
+            continue;
+        const spot = ownValue(spots, id);
+        if (spot === undefined)
+            continue;
+        if (spot.currency === undefined) {
+            warnings.push(`observations.spots['${id}'] states no currency — it cannot price a trade; '${id}' is unpriced here.`);
+            continue;
+        }
+        // A spot says nothing about a contract's size. A share is 1 by construction; an OCC option
+        // symbol that is not held has no multiplier anywhere in this input, and the share default
+        // would size a 100-share contract at 1% of its cash value — so it stays unresolved, with the
+        // reason, rather than priced wrong.
+        if (ownValue(contractMultipliers, id) === undefined && isOccOptionSymbol(id)) {
+            unresolvedTargets.push({
+                key: `instrumentId:${id}`,
+                group: { instrumentId: id },
+                reason: `'${id}' is an OCC option symbol that is not held, so its contract multiplier is unknown and a market spot alone cannot size it (the share default of 1 would value each contract at one share). Hold it in the ledger with its contractMultiplier, or trade it through normalizeTradePlan with input.instruments.`,
+            });
+            continue;
+        }
+        setOwnValue(prices, id, { price: spot.price, currency: spot.currency });
+    }
+    const instrumentCurrency = {};
+    const priceInBase = new Map();
+    for (const id of Object.keys(prices).sort()) {
+        const row = ownValue(prices, id);
+        setOwnValue(instrumentCurrency, id, row.currency);
+        priceInBase.set(id, toBase(row.price, row.currency, `the ${id} mark (${row.currency})`));
+    }
+    const currentWeight = (id) => (heldValueBase.get(id) ?? 0) / netAssetValue;
+    const currentWeights = {};
+    for (const id of Object.keys(heldQuantity)) {
+        setOwnValue(currentWeights, id, currentWeight(id));
+    }
+    const expanded = expandTargets(functionName, {
+        targets: resolved.targets,
+        universe: expansionUniverse,
+        instrumentClassification: classification,
+        instrumentCurrency,
+        currentWeights,
+        sleeves,
+        withinGroupAllocation: policy.withinGroupAllocation,
+        defaultDriftBand: policy.driftBand,
+    });
+    unresolvedTargets.push(...expanded.unresolved);
+    warnings.push(...expanded.warnings);
+    const targetRows = new Map();
+    for (const t of expanded.instrumentTargets) {
+        targetRows.set(t.instrumentId, {
+            target: t.targetWeight,
+            driftBand: t.driftBand,
+            sourceGroups: [...t.sourceGroups],
+        });
+    }
+    for (const id of [...restrictedHeld].sort()) {
+        const named = resolved.targets.find((t) => t.group.instrumentId === id);
+        if (named !== undefined) {
+            unresolvedTargets.push({
+                key: `instrumentId:${id}`,
+                group: { instrumentId: id },
+                reason: `'${id}' is in policy.restrictedInstruments and is also named by a target (weight ${named.weight ?? 'risk budget'}) — a restricted instrument cannot carry a target.`,
+            });
+            targetRows.set(id, {
+                target: null,
+                driftBand: policy.driftBand ?? null,
+                sourceGroups: ['policy:restrictedInstruments'],
+            });
+            continue;
+        }
+        targetRows.set(id, {
+            target: 0,
+            driftBand: policy.driftBand ?? null,
+            sourceGroups: ['policy:restrictedInstruments'],
+        });
+        warnings.push(`'${id}' is in policy.restrictedInstruments — its target is 0 (sell to zero); its ${String(ownValue(heldQuantity, id))} held units are excluded from every group target.`);
+    }
+    for (const id of [...disallowedHeld].sort()) {
+        unresolvedTargets.push({
+            key: `instrumentId:${id}`,
+            group: { instrumentId: id },
+            reason: `'${id}' is held (${String(ownValue(heldQuantity, id))} units) but is not in policy.allowedInstruments — add it to allowedInstruments to keep managing it, or to restrictedInstruments to sell it to zero; it is not traded here.`,
+        });
+        targetRows.set(id, {
+            target: null,
+            driftBand: policy.driftBand ?? null,
+            sourceGroups: [],
+        });
+    }
+    const cashTargetWeight = expanded.cashTarget?.targetWeight ?? null;
+    const cashBand = expanded.cashTarget?.driftBand ?? null;
+    // ---- the flow ----
+    const netAssetValueAfterFlow = netAssetValue + flowAmount;
+    if (!(netAssetValueAfterFlow > 0)) {
+        throw new InputError(`${functionName}: the withdrawal of ${-flowAmount} ${baseCurrency} exceeds the managed net asset value ${netAssetValue} — nothing would remain to rebalance.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'externalFlow.amount' },
+        });
+    }
+    const holdAsCash = flowAmount > 0 && policy.contributionHandling === 'hold-as-cash';
+    const investContribution = flowAmount > 0 && policy.contributionHandling === 'invest-to-targets';
+    const sizingNav = holdAsCash ? netAssetValue : netAssetValueAfterFlow;
+    const flowHandling = flow === null
+        ? 'No external flow: the plan is funded from settled cash and sells.'
+        : flowAmount > 0
+            ? holdAsCash
+                ? `A contribution of ${flowAmount} ${baseCurrency} is held as cash (policy.contributionHandling 'hold-as-cash'): instrument targets are sized over the pre-flow NAV ${netAssetValue}; the contribution stays in cash and only ${scope === 'drift-only' ? 'drift' : 'to-target'} trades run.`
+                : `A contribution of ${flowAmount} ${baseCurrency} is invested to targets (policy.contributionHandling 'invest-to-targets'): targets are sized over the post-flow NAV ${netAssetValueAfterFlow} and the new cash funds the most underweight instruments first${scope === 'drift-only' ? ', capped at the contribution; the remainder stays in cash' : ''}.`
+            : policy.withdrawalHandling === 'raise-from-overweights'
+                ? `A withdrawal of ${-flowAmount} ${baseCurrency} is raised from settled cash above the floor first, then by selling the most overweight holdings first (policy.withdrawalHandling 'raise-from-overweights'); targets are sized over the post-flow NAV ${netAssetValueAfterFlow}${scope === 'to-target' ? ' — in scope to-target every holding moves to target, so the handling only labels which sells raise the withdrawal' : ''}.`
+                : `A withdrawal of ${-flowAmount} ${baseCurrency} is raised from settled cash above the floor first, then by selling every held instrument proportionally to its value (policy.withdrawalHandling 'pro-rata'); targets are sized over the post-flow NAV ${netAssetValueAfterFlow}${scope === 'to-target' ? ' — in scope to-target every holding moves to target, so the handling only labels which sells raise the withdrawal' : ''}.`;
+    // ---- sizing: ONE allocatePortfolio pass over instrument-level targets ----
+    const inlineTargets = [];
+    const sizedHoldings = {};
+    for (const [id, row] of [...targetRows.entries()].sort((a, b) => compareIds(a[0], b[0]))) {
+        if (row.target === null)
+            continue;
+        inlineTargets.push({ group: { instrumentId: id }, weight: row.target });
+        const held = ownValue(heldQuantity, id);
+        if (held !== undefined)
+            setOwnValue(sizedHoldings, id, held);
+    }
+    if (cashTargetWeight !== null) {
+        inlineTargets.push({ group: { assetClass: CASH_ASSET_CLASS }, weight: cashTargetWeight });
+    }
+    const sizedPrices = {};
+    for (const id of Object.keys(prices)) {
+        if (targetRows.get(id)?.target !== null && targetRows.has(id)) {
+            setOwnValue(sizedPrices, id, ownValue(prices, id));
+        }
+    }
+    const candidates = [];
+    const dustSkipped = [];
+    if (inlineTargets.length > 0) {
+        const allocationInput = {
+            policy: { targets: inlineTargets },
+            asOf,
+            baseCurrency,
+            netAssetValue: sizingNav,
+            prices: sizedPrices,
+            currentHoldings: sizedHoldings,
+            contractMultipliers,
+            ...(input.currencyConversions !== undefined
+                ? { currencyConversions: input.currencyConversions }
+                : {}),
+            ...(input.lotSizes !== undefined ? { lotSizes: input.lotSizes } : {}),
+            ...(input.defaultLotSize !== undefined ? { defaultLotSize: input.defaultLotSize } : {}),
+            ...(input.minimumNotional !== undefined ? { minimumNotional: input.minimumNotional } : {}),
+            ...(input.transactionCosts !== undefined ? { transactionCosts: input.transactionCosts } : {}),
+        };
+        const allocation = allocatePortfolio(allocationInput);
+        for (const row of allocation.unresolved) {
+            if (!unresolvedTargets.some((u) => u.key === row.key))
+                unresolvedTargets.push(row);
+        }
+        dustSkipped.push(...allocation.dust);
+        for (const row of allocation.allocations) {
+            if (row.tradeQuantity === 0)
+                continue;
+            candidates.push({
+                instrumentId: row.instrumentId,
+                quantity: row.tradeQuantity,
+                priceInBase: row.priceInBaseCurrency,
+                markPricePerUnit: row.price,
+                currency: row.currency,
+                lotSize: row.lotSize,
+            });
+        }
+    }
+    else {
+        warnings.push('no target resolved to an instrument or cash weight — nothing can be sized; see unresolvedTargets.');
+    }
+    // ---- drift (before) ----
+    const cashWeightBefore = totalCashBase / netAssetValue;
+    const outsideInstruments = new Set();
+    for (const [id, row] of targetRows) {
+        if (row.target === null || row.driftBand === null)
+            continue;
+        if (Math.abs(currentWeight(id) - row.target) > row.driftBand + WEIGHT_NOISE) {
+            outsideInstruments.add(id);
+        }
+    }
+    const groupRows = expanded.groupTargets.filter((g) => !isCashTargetGroup(g.group));
+    const groupCurrent = new Map();
+    const outsideGroups = new Set();
+    for (const group of groupRows) {
+        const current = group.members.reduce((sum, id) => sum + currentWeight(id), 0);
+        groupCurrent.set(group.key, current);
+        if (group.driftBand !== null &&
+            Math.abs(current - group.targetWeight) > group.driftBand + WEIGHT_NOISE) {
+            outsideGroups.add(group.key);
+        }
+    }
+    const cashOutside = cashTargetWeight !== null &&
+        cashBand !== null &&
+        Math.abs(cashWeightBefore - cashTargetWeight) > cashBand + WEIGHT_NOISE;
+    const instrumentIsOutside = (id) => outsideInstruments.has(id) ||
+        (targetRows.get(id)?.sourceGroups ?? []).some((key) => outsideGroups.has(key));
+    // ---- selection: which sized trades the scope and the flow keep ----
+    const kept = new Map();
+    const sizedCurrentWeight = (id) => (heldValueBase.get(id) ?? 0) / sizingNav;
+    const underweightBy = (id) => (targetRows.get(id)?.target ?? 0) - sizedCurrentWeight(id);
+    const byId = (a, b) => compareIds(a.instrumentId, b.instrumentId);
+    if (investContribution) {
+        const buys = candidates
+            .filter((c) => c.quantity > 0)
+            .sort((a, b) => underweightBy(b.instrumentId) - underweightBy(a.instrumentId) || byId(a, b));
+        let remaining = flowAmount;
+        for (const candidate of buys) {
+            const notional = candidate.quantity * candidate.priceInBase;
+            if (scope === 'to-target') {
+                if (remaining <= tolerance)
+                    break;
+                kept.set(candidate.instrumentId, {
+                    candidate,
+                    quantity: candidate.quantity,
+                    reason: 'contribution',
+                });
+                remaining -= notional;
+                continue;
+            }
+            if (remaining <= tolerance)
+                break;
+            if (notional <= remaining + tolerance) {
+                kept.set(candidate.instrumentId, {
+                    candidate,
+                    quantity: candidate.quantity,
+                    reason: 'contribution',
+                });
+                remaining -= notional;
+            }
+            else {
+                const trimmed = roundTowardZeroToLot(remaining / candidate.priceInBase, candidate.lotSize);
+                if (trimmed > 0) {
+                    kept.set(candidate.instrumentId, {
+                        candidate,
+                        quantity: trimmed,
+                        reason: 'contribution',
+                    });
+                    remaining -= trimmed * candidate.priceInBase;
+                }
+            }
+        }
+        if (scope === 'drift-only' && remaining > tolerance) {
+            warnings.push(`the contribution exceeds the underweight buys by ${remaining} ${baseCurrency}; the remainder stays in cash (scope 'drift-only' sells nothing to reach targets).`);
+        }
+    }
+    for (const candidate of [...candidates].sort(byId)) {
+        if (kept.has(candidate.instrumentId))
+            continue;
+        if (scope === 'to-target') {
+            kept.set(candidate.instrumentId, {
+                candidate,
+                quantity: candidate.quantity,
+                reason: 'to-target',
+            });
+        }
+        else if (instrumentIsOutside(candidate.instrumentId)) {
+            kept.set(candidate.instrumentId, {
+                candidate,
+                quantity: candidate.quantity,
+                reason: 'drift',
+            });
+        }
+    }
+    if (scope === 'drift-only' && cashOutside && kept.size === 0) {
+        warnings.push(`cash is outside its band (${cashWeightBefore} vs target ${cashTargetWeight} ± ${cashBand}) but no instrument or group is — scope 'drift-only' proposes nothing; use scope 'to-target' to move cash to target.`);
+    }
+    // Cash floor: the larger of the two spellings; 0 when neither is declared (no borrowing).
+    const reserve = Math.max(policy.minimumCash ?? -Infinity, policy.minimumCashWeight === undefined
+        ? -Infinity
+        : policy.minimumCashWeight * netAssetValueAfterFlow, policy.minimumCash === undefined && policy.minimumCashWeight === undefined ? 0 : -Infinity);
+    const unresolvedConstraints = [];
+    const keptBuys = () => [...kept.values()].reduce((sum, k) => sum + (k.quantity > 0 ? k.quantity * k.candidate.priceInBase : 0), 0);
+    const keptSells = () => [...kept.values()].reduce((sum, k) => sum + (k.quantity < 0 ? -k.quantity * k.candidate.priceInBase : 0), 0);
+    if (flowAmount < 0) {
+        const needed = -flowAmount;
+        if (scope === 'to-target') {
+            const sells = [...kept.values()]
+                .filter((k) => k.quantity < 0)
+                .sort((a, b) => underweightBy(a.candidate.instrumentId) - underweightBy(b.candidate.instrumentId) ||
+                byId(a.candidate, b.candidate));
+            let remaining = needed;
+            for (const k of sells) {
+                if (remaining <= tolerance)
+                    break;
+                k.reason = 'withdrawal';
+                remaining -= -k.quantity * k.candidate.priceInBase;
+            }
+        }
+        else {
+            let toRaise = needed + reserve - settledCashBase - keptSells() + keptBuys();
+            if (toRaise > tolerance) {
+                if (policy.withdrawalHandling === 'raise-from-overweights') {
+                    const sells = candidates
+                        .filter((c) => c.quantity < 0 && !kept.has(c.instrumentId))
+                        .sort((a, b) => underweightBy(a.instrumentId) - underweightBy(b.instrumentId) || byId(a, b));
+                    for (const candidate of sells) {
+                        if (toRaise <= tolerance)
+                            break;
+                        const notional = -candidate.quantity * candidate.priceInBase;
+                        if (notional <= toRaise + tolerance) {
+                            kept.set(candidate.instrumentId, {
+                                candidate,
+                                quantity: candidate.quantity,
+                                reason: 'withdrawal',
+                            });
+                            toRaise -= notional;
+                        }
+                        else {
+                            const trimmed = roundTowardZeroToLot(toRaise / candidate.priceInBase, candidate.lotSize);
+                            if (trimmed > 0) {
+                                kept.set(candidate.instrumentId, {
+                                    candidate,
+                                    quantity: -trimmed,
+                                    reason: 'withdrawal',
+                                });
+                                toRaise -= trimmed * candidate.priceInBase;
+                            }
+                        }
+                    }
+                }
+                else {
+                    const sellable = [...heldValueBase.entries()]
+                        .filter(([id, value]) => value > 0 &&
+                        !kept.has(id) &&
+                        targetRows.get(id)?.target !== null &&
+                        priceInBase.has(id))
+                        .sort((a, b) => compareIds(a[0], b[0]));
+                    const total = sellable.reduce((sum, [, value]) => sum + value, 0);
+                    const target = toRaise;
+                    for (const [id, value] of sellable) {
+                        const base = priceInBase.get(id);
+                        const price = ownValue(prices, id);
+                        const share = (target * value) / total;
+                        const quantity = Math.min(roundTowardZeroToLot(share / base, lotSizeFor(sizing, id)), ownValue(heldQuantity, id) ?? 0);
+                        if (quantity <= QUANTITY_DUST)
+                            continue;
+                        kept.set(id, {
+                            candidate: {
+                                instrumentId: id,
+                                quantity: -quantity,
+                                priceInBase: base,
+                                markPricePerUnit: price.price,
+                                currency: price.currency,
+                                lotSize: lotSizeFor(sizing, id),
+                            },
+                            quantity: -quantity,
+                            reason: 'withdrawal',
+                        });
+                        toRaise -= quantity * base;
+                    }
+                }
+                if (toRaise > tolerance) {
+                    unresolvedConstraints.push({
+                        constraint: 'withdrawal',
+                        status: 'violated',
+                        reason: `the withdrawal of ${needed} ${baseCurrency} plus the cash floor ${reserve} need ${toRaise} ${baseCurrency} more than settled cash and the proposed sells raise (${policy.withdrawalHandling} over the ${scope === 'drift-only' ? 'holdings inside their bands' : 'book'}) — lot rounding or the holdings cannot cover it; widen the scope or lower the floor.`,
+                        value: toRaise,
+                        limit: needed,
+                    });
+                }
+            }
+        }
+    }
+    // ---- turnover cap and cash floor: trim, never relax (≤ 3 passes) ----
+    const requiredTurnover = [...kept.values()].reduce((sum, k) => sum + Math.abs(k.quantity) * k.candidate.priceInBase, 0) /
+        netAssetValueAfterFlow;
+    let turnoverCapped = false;
+    let cashCapped = false;
+    let cashViolated = null;
+    let iterations = 0;
+    let converged = false;
+    const rescale = (k, factor) => {
+        k.quantity = roundTowardZeroToLot(k.quantity * factor, k.candidate.lotSize);
+    };
+    while (iterations < MAXIMUM_ITERATIONS) {
+        iterations += 1;
+        let changed = false;
+        const gross = [...kept.values()].reduce((sum, k) => sum + Math.abs(k.quantity) * k.candidate.priceInBase, 0);
+        const turnover = gross / netAssetValueAfterFlow;
+        if (policy.maximumTurnover !== undefined &&
+            turnover > policy.maximumTurnover + AMOUNT_TOLERANCE_FRACTION) {
+            const factor = policy.maximumTurnover / turnover;
+            for (const k of kept.values())
+                rescale(k, factor);
+            turnoverCapped = true;
+            changed = true;
+        }
+        const buys = keptBuys();
+        const available = settledCashBase + flowAmount + keptSells() - reserve;
+        if (buys > available + tolerance) {
+            if (buys > 0) {
+                const factor = Math.max(0, available) / buys;
+                for (const k of kept.values())
+                    if (k.quantity > 0)
+                        rescale(k, factor);
+                cashCapped = true;
+                changed = true;
+            }
+            else if (cashViolated === null) {
+                cashViolated = available;
+            }
+        }
+        if (!changed) {
+            converged = true;
+            break;
+        }
+    }
+    {
+        const gross = [...kept.values()].reduce((sum, k) => sum + Math.abs(k.quantity) * k.candidate.priceInBase, 0);
+        const turnoverOk = policy.maximumTurnover === undefined ||
+            gross / netAssetValueAfterFlow <= policy.maximumTurnover + AMOUNT_TOLERANCE_FRACTION;
+        const fundingOk = keptBuys() <= settledCashBase + flowAmount + keptSells() - reserve + tolerance;
+        converged = converged && turnoverOk && fundingOk;
+        if (!converged) {
+            unresolvedConstraints.push({
+                constraint: 'convergence',
+                status: 'violated',
+                reason: `the turnover cap and the cash floor did not settle in ${iterations} passes (lot rounding keeps the trimmed plan ${turnoverOk ? 'unfunded' : 'above the turnover cap'}) — the trades listed are the last pass; loosen the lot sizes or the constraint.`,
+                value: gross / netAssetValueAfterFlow,
+                limit: policy.maximumTurnover ?? null,
+            });
+        }
+    }
+    // Trades rounded away, or turned to dust by the trimming.
+    for (const [id, k] of [...kept.entries()].sort((a, b) => compareIds(a[0], b[0]))) {
+        if (k.quantity === 0) {
+            kept.delete(id);
+            warnings.push(`the ${id} trade rounded to zero lots after trimming and is dropped.`);
+            continue;
+        }
+        const notional = k.quantity * k.candidate.priceInBase;
+        if (sizing.minimumNotional !== null && Math.abs(notional) < sizing.minimumNotional) {
+            kept.delete(id);
+            dustSkipped.push({
+                instrumentId: id,
+                tradeNotional: notional,
+                reason: `after trimming, the ${sideOf(k.quantity)} of ${Math.abs(k.quantity)} ${id} (|notional| ${Math.abs(notional)}) is below minimumNotional ${sizing.minimumNotional} — skipped.`,
+            });
+        }
+    }
+    // ---- account assignment, lot previews, costs ----
+    const trades = [];
+    const bookTrade = (accountId, k, quantity, closing) => {
+        const c = k.candidate;
+        const notionalBase = quantity * c.priceInBase;
+        const cost = estimateTradeCost(sizing.transactionCosts, quantity, notionalBase);
+        let lotSelection = null;
+        let lotSelectionReason = null;
+        if (closing === null) {
+            lotSelectionReason = 'the trade opens or extends a position; nothing is relieved.';
+        }
+        else if (state.lotRelief === 'specific-lot') {
+            lotSelectionReason =
+                'specific-lot relief needs caller lot selections — the ledger relieves only the lots a fill names, so no preview is possible here.';
+        }
+        else {
+            lotSelection = previewLots(closing, quantity, state.lotRelief);
+        }
+        trades.push({
+            accountId,
+            instrumentId: c.instrumentId,
+            side: sideOf(k.quantity),
+            quantity,
+            markPricePerUnit: c.markPricePerUnit,
+            currency: c.currency,
+            estimatedNotional: notionalBase,
+            estimatedCommission: cost.commission,
+            estimatedSpreadCost: cost.spread,
+            estimatedSlippageCost: cost.slippage,
+            lotSelection,
+            lotSelectionReason,
+            reason: k.reason,
+        });
+    };
+    for (const [id, k] of [...kept.entries()].sort((a, b) => compareIds(a[0], b[0]))) {
+        let remaining = Math.abs(k.quantity);
+        const positions = (positionsByInstrument.get(id) ?? [])
+            .filter((p) => (k.quantity < 0 ? p.quantity > 0 : p.quantity < 0))
+            .sort((a, b) => compareIds(a.accountId, b.accountId));
+        for (const position of positions) {
+            if (remaining <= QUANTITY_DUST)
+                break;
+            const take = Math.min(remaining, Math.abs(position.quantity));
+            if (take <= QUANTITY_DUST)
+                continue;
+            bookTrade(position.accountId, k, take, position);
+            remaining -= take;
+        }
+        if (remaining > QUANTITY_DUST)
+            bookTrade(tradingAccountId, k, remaining, null);
+    }
+    trades.sort((a, b) => compareIds(a.instrumentId, b.instrumentId) || compareIds(a.accountId, b.accountId));
+    // The plan never moves cash between accounts: an account whose own settled cash, sells, and
+    // (for the trading account) the flow cannot cover the buys booked to it is said, not hidden.
+    for (const accountId of accountsConsidered) {
+        const accountBuys = trades
+            .filter((t) => t.accountId === accountId && t.side === 'buy')
+            .reduce((sum, t) => sum + t.estimatedNotional, 0);
+        if (accountBuys <= tolerance)
+            continue;
+        const accountSells = trades
+            .filter((t) => t.accountId === accountId && t.side === 'sell')
+            .reduce((sum, t) => sum + t.estimatedNotional, 0);
+        const accountFlow = accountId === tradingAccountId ? flowAmount : 0;
+        const accountSettled = settledByAccount.get(accountId) ?? 0;
+        const shortfall = accountBuys - (accountSettled + accountSells + accountFlow);
+        if (shortfall > tolerance) {
+            warnings.push(`buys booked to '${accountId}' (${accountBuys} ${baseCurrency}) exceed its own settled cash ${accountSettled} + sells ${accountSells}${accountFlow !== 0 ? ` + flow ${accountFlow}` : ''} by ${shortfall} — the plan does not move cash between accounts; a cash.transfer into '${accountId}' is needed before execution.`);
+        }
+    }
+    // ---- post-trade book ----
+    const buysTotal = trades.reduce((s, t) => s + (t.side === 'buy' ? t.estimatedNotional : 0), 0);
+    const sellsTotal = trades.reduce((s, t) => s + (t.side === 'sell' ? t.estimatedNotional : 0), 0);
+    const grossTotal = buysTotal + sellsTotal;
+    const postQuantity = new Map();
+    for (const id of new Set([...Object.keys(heldQuantity), ...kept.keys()])) {
+        postQuantity.set(id, (ownValue(heldQuantity, id) ?? 0) + (kept.get(id)?.quantity ?? 0));
+    }
+    const postCash = totalCashBase + flowAmount - buysTotal + sellsTotal;
+    const postSettled = settledCashBase + flowAmount - buysTotal + sellsTotal;
+    const weightsBefore = new Map();
+    const weightsAfter = new Map();
+    const instrumentIds = [...new Set([...targetRows.keys(), ...Object.keys(heldQuantity)])].sort();
+    for (const id of instrumentIds) {
+        weightsBefore.set(id, currentWeight(id));
+        const base = priceInBase.get(id);
+        const quantity = postQuantity.get(id) ?? 0;
+        weightsAfter.set(id, base === undefined
+            ? (heldValueBase.get(id) ?? 0) / netAssetValueAfterFlow
+            : (quantity * base) / netAssetValueAfterFlow);
+    }
+    const cashWeightAfter = postCash / netAssetValueAfterFlow;
+    const instrumentWeights = instrumentIds.map((id) => {
+        const row = targetRows.get(id) ?? { target: null, driftBand: null, sourceGroups: [] };
+        return {
+            instrumentId: id,
+            current: weightsBefore.get(id),
+            target: row.target,
+            postTrade: weightsAfter.get(id),
+            driftBand: row.driftBand,
+            outsideBand: outsideInstruments.has(id),
+            sourceGroups: [...row.sourceGroups],
+        };
+    });
+    const groupWeights = groupRows
+        .map((group) => ({
+        key: group.key,
+        current: groupCurrent.get(group.key),
+        target: group.targetWeight,
+        postTrade: group.members.reduce((sum, id) => sum + (weightsAfter.get(id) ?? 0), 0),
+        driftBand: group.driftBand,
+        outsideBand: outsideGroups.has(group.key),
+    }))
+        .sort((a, b) => compareIds(a.key, b.key));
+    // ---- objective and risk ----
+    const driftDistance = (weights, cashWeight) => {
+        let total = 0;
+        for (const [id, row] of targetRows) {
+            if (row.target === null)
+                continue;
+            total += Math.abs((weights.get(id) ?? 0) - row.target);
+        }
+        if (cashTargetWeight !== null)
+            total += Math.abs(cashWeight - cashTargetWeight);
+        return total / 2;
+    };
+    const benchmark = policy.benchmark ?? policy.model?.benchmark;
+    const constituents = benchmark?.constituents;
+    const trackingDistance = (weights, cashWeight) => {
+        if (constituents === undefined)
+            return null;
+        const benchmarkWeight = new Map(constituents.map((c) => [c.instrumentId, c.weight]));
+        const ids = new Set([...weights.keys(), ...benchmarkWeight.keys()]);
+        let total = Math.abs(cashWeight);
+        for (const id of ids)
+            total += Math.abs((weights.get(id) ?? 0) - (benchmarkWeight.get(id) ?? 0));
+        return total / 2;
+    };
+    if (constituents === undefined) {
+        warnings.push(benchmark === undefined
+            ? 'trackingDistance is null: the policy declares no benchmark.'
+            : `trackingDistance is null: benchmark '${benchmark.benchmarkId}' declares no constituents.`);
+    }
+    const objectiveBefore = {
+        driftDistance: driftDistance(weightsBefore, cashWeightBefore),
+        trackingDistance: trackingDistance(weightsBefore, cashWeightBefore),
+    };
+    const objectiveAfter = {
+        driftDistance: driftDistance(weightsAfter, cashWeightAfter),
+        trackingDistance: trackingDistance(weightsAfter, cashWeightAfter),
+    };
+    if (turnoverCapped) {
+        unresolvedConstraints.push({
+            constraint: 'maximumTurnover',
+            status: 'capped',
+            reason: `targets need ${requiredTurnover} turnover; capped at ${policy.maximumTurnover} — residual drift ${objectiveAfter.driftDistance} remains.`,
+            value: requiredTurnover,
+            limit: policy.maximumTurnover ?? null,
+        });
+    }
+    if (cashCapped) {
+        unresolvedConstraints.push({
+            constraint: 'minimumCash',
+            status: 'capped',
+            reason: `buys were scaled to the ${settledCashBase + flowAmount + sellsTotal - reserve} ${baseCurrency} available above the cash floor ${reserve} (settled cash ${settledCashBase} + flow ${flowAmount} + sells ${sellsTotal}) — residual drift ${objectiveAfter.driftDistance} remains.`,
+            value: postSettled,
+            limit: reserve,
+        });
+    }
+    if (cashViolated !== null) {
+        unresolvedConstraints.push({
+            constraint: 'minimumCash',
+            status: 'violated',
+            reason: `post-trade settled cash ${postSettled} ${baseCurrency} is below the cash floor ${reserve} by ${reserve - postSettled} and no buys remain to scale — raise more cash or lower the floor.`,
+            value: postSettled,
+            limit: reserve,
+        });
+    }
+    // ---- post-trade hard limits: reported, never auto-fixed ----
+    const limits = policy.limits;
+    const estimates = {
+        commission: trades.reduce((s, t) => s + t.estimatedCommission, 0),
+        spread: trades.reduce((s, t) => s + t.estimatedSpreadCost, 0),
+        slippage: trades.reduce((s, t) => s + t.estimatedSlippageCost, 0),
+        totalCost: 0,
+        turnover: grossTotal / netAssetValueAfterFlow,
+    };
+    estimates.totalCost = estimates.commission + estimates.spread + estimates.slippage;
+    if (limits?.maximumPositionWeight !== undefined) {
+        for (const id of instrumentIds) {
+            const w = Math.abs(weightsAfter.get(id));
+            if (w > limits.maximumPositionWeight + WEIGHT_NOISE) {
+                unresolvedConstraints.push({
+                    constraint: 'maximumPositionWeight',
+                    status: 'violated',
+                    reason: `'${id}' would be ${w} of NAV after the trades, above limits.maximumPositionWeight ${limits.maximumPositionWeight} — the targets ask for it; nothing was relaxed.`,
+                    value: w,
+                    limit: limits.maximumPositionWeight,
+                });
+            }
+        }
+    }
+    if (limits?.maximumGroupWeights !== undefined) {
+        for (const limit of limits.maximumGroupWeights) {
+            const key = targetGroupKey(limit.group);
+            const members = groupMembers(limit.group, key, instrumentIds, classification, instrumentCurrency, sleeves);
+            const value = key === `assetClass:${CASH_ASSET_CLASS}`
+                ? Math.abs(cashWeightAfter)
+                : members.reduce((sum, id) => sum + Math.abs(weightsAfter.get(id) ?? 0), 0);
+            if (value > limit.maximumWeight + WEIGHT_NOISE) {
+                unresolvedConstraints.push({
+                    constraint: `maximumGroupWeights:${key}`,
+                    status: 'violated',
+                    reason: `'${key}' would be ${value} of NAV after the trades (${members.join(', ') || 'cash'}), above its maximumWeight ${limit.maximumWeight}.`,
+                    value,
+                    limit: limit.maximumWeight,
+                });
+            }
+        }
+    }
+    const riskBefore = riskPoint(weightsBefore, cashWeightBefore);
+    const riskAfter = riskPoint(weightsAfter, cashWeightAfter);
+    if (limits?.maximumGrossLeverage !== undefined &&
+        riskAfter.grossLeverage > limits.maximumGrossLeverage + WEIGHT_NOISE) {
+        unresolvedConstraints.push({
+            constraint: 'maximumGrossLeverage',
+            status: 'violated',
+            reason: `gross exposure would be ${riskAfter.grossLeverage} × NAV after the trades, above limits.maximumGrossLeverage ${limits.maximumGrossLeverage}.`,
+            value: riskAfter.grossLeverage,
+            limit: limits.maximumGrossLeverage,
+        });
+    }
+    if (limits?.minimumSettledCash !== undefined &&
+        postSettled < limits.minimumSettledCash - tolerance) {
+        unresolvedConstraints.push({
+            constraint: 'minimumSettledCash',
+            status: 'violated',
+            reason: `post-trade settled cash would be ${postSettled} ${baseCurrency}, below limits.minimumSettledCash ${limits.minimumSettledCash}.`,
+            value: postSettled,
+            limit: limits.minimumSettledCash,
+        });
+    }
+    if (policy.maximumEstimatedTransactionCost !== undefined &&
+        estimates.totalCost > policy.maximumEstimatedTransactionCost + tolerance) {
+        unresolvedConstraints.push({
+            constraint: 'maximumEstimatedTransactionCost',
+            status: 'violated',
+            reason: `the estimated transaction cost ${estimates.totalCost} ${baseCurrency} exceeds policy.maximumEstimatedTransactionCost ${policy.maximumEstimatedTransactionCost}.`,
+            value: estimates.totalCost,
+            limit: policy.maximumEstimatedTransactionCost,
+        });
+    }
+    if (limits?.maximumDaysToLiquidate !== undefined) {
+        const missing = [];
+        for (const id of instrumentIds) {
+            const quantity = Math.abs(postQuantity.get(id) ?? 0);
+            if (quantity <= QUANTITY_DUST)
+                continue;
+            const volume = ownValue(volumes, id);
+            if (volume === undefined) {
+                missing.push(id);
+                continue;
+            }
+            const days = quantity / (volume * LIQUIDITY_PARTICIPATION_RATE);
+            if (days > limits.maximumDaysToLiquidate + WEIGHT_NOISE) {
+                unresolvedConstraints.push({
+                    constraint: 'maximumDaysToLiquidate',
+                    status: 'violated',
+                    reason: `'${id}' would take ${days} days to liquidate ${quantity} units at ${LIQUIDITY_PARTICIPATION_RATE} of its ${volume}/day volume, above limits.maximumDaysToLiquidate ${limits.maximumDaysToLiquidate}.`,
+                    value: days,
+                    limit: limits.maximumDaysToLiquidate,
+                });
+            }
+        }
+        if (missing.length > 0) {
+            unresolvedConstraints.push({
+                constraint: 'maximumDaysToLiquidate',
+                status: 'unverifiable',
+                reason: `limits.maximumDaysToLiquidate ${limits.maximumDaysToLiquidate} cannot be evaluated for ${missing.join(', ')} — supply averageDailyVolumes for every post-trade position.`,
+                value: null,
+                limit: limits.maximumDaysToLiquidate,
+            });
+        }
+    }
+    unresolvedConstraints.sort((a, b) => compareIds(a.constraint, b.constraint) || compareIds(a.reason, b.reason));
+    // ---- the plan artifact ----
+    const policyContentHash = contentHash(policy);
+    const planTrades = trades
+        .map((t) => ({
+        accountId: t.accountId,
+        instrumentId: t.instrumentId,
+        side: t.side,
+        quantity: t.quantity,
+        currency: t.currency,
+        referencePricePerUnit: t.markPricePerUnit,
+        // The ledger's multiplier for a held instrument; 1 for a plain instrument priced from a spot
+        // (an OCC symbol never reaches here without one — see the spot loop above).
+        contractMultiplier: ownValue(contractMultipliers, t.instrumentId) ?? 1,
+        estimatedNotional: t.quantity * t.markPricePerUnit * (ownValue(contractMultipliers, t.instrumentId) ?? 1),
+    }))
+        .sort((a, b) => compareIds(a.accountId, b.accountId) ||
+        compareIds(a.instrumentId, b.instrumentId) ||
+        compareIds(a.side, b.side));
+    const planBody = {
+        kind: TRADE_PLAN_KIND,
+        schemaVersion: TRADE_PLAN_SCHEMA_VERSION,
+        asOf,
+        baseCurrency,
+        ...(state.portfolioId !== undefined ? { portfolioId: state.portfolioId } : {}),
+        policyContentHash,
+        trades: planTrades,
+    };
+    const plan = { ...planBody, contentHash: contentHash(planBody) };
+    const sortedUnresolvedTargets = sortUnresolved(unresolvedTargets);
+    const feasible = sortedUnresolvedTargets.length === 0 &&
+        converged &&
+        unresolvedConstraints.every((row) => row.status === 'capped');
+    dustSkipped.sort((a, b) => compareIds(a.instrumentId, b.instrumentId));
+    return deepFreeze(requireRepresentableResult(functionName, {
+        asOf,
+        baseCurrency,
+        netAssetValue,
+        netAssetValueAfterFlow,
+        weights: {
+            instruments: instrumentWeights,
+            groups: groupWeights,
+            cash: { current: cashWeightBefore, target: cashTargetWeight, postTrade: cashWeightAfter },
+        },
+        cash: {
+            available: settledCashBase + flowAmount,
+            raised: sellsTotal,
+            used: buysTotal,
+            remainingReserve: postSettled,
+            minimumReserve: reserve,
+        },
+        trades,
+        estimates,
+        objective: {
+            before: objectiveBefore,
+            after: objectiveAfter,
+            convention: 'driftDistance = Σ|weight − target| ÷ 2 over instrument targets and cash (0 = at target, 1 = fully misallocated); trackingDistance = active share vs the benchmark constituents, Σ|weight − benchmark weight| ÷ 2 with cash as an asset the benchmark does not hold — null when the policy names no constituents.',
+        },
+        risk: { before: riskBefore, after: riskAfter },
+        unresolvedTargets: sortedUnresolvedTargets,
+        unresolvedConstraints,
+        convergence: { converged, iterations },
+        dust: {
+            skipped: dustSkipped,
+            aggregateNotional: dustSkipped.reduce((sum, row) => sum + row.tradeNotional, 0),
+        },
+        feasible,
+        plan,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            lotRelief: state.lotRelief,
+            targetSource: resolved.source,
+            scope,
+            flowHandling,
+            rounding: describeRounding(sizing, [...kept.keys()].filter((id) => lotSizeFor(sizing, id) === null).sort()),
+            costModel: `${describeCostModel(sizing.transactionCosts)} commissionPerTrade applies per proposed trade row (one per account × instrument).`,
+            liquidityParticipationRate: LIQUIDITY_PARTICIPATION_RATE,
+            conventions: CONVENTIONS,
+        },
+        diagnostics: {
+            warnings,
+            accountsConsidered,
+            accountsExcluded,
+            tradeCount: trades.length,
+            dustCount: dustSkipped.length,
+        },
+    }));
+}
+/** The instruments a group-weight limit covers, from the same identity vocabulary the targets use. */
+function groupMembers(group, key, instrumentIds, classification, instrumentCurrency, sleeves) {
+    if (group.instrumentId !== undefined)
+        return [group.instrumentId];
+    if (group.sleeveId !== undefined)
+        return sleeveLeafMembers(group.sleeveId, sleeves);
+    return instrumentIds.filter((id) => instrumentGroupKeys(id, ownValue(classification, id), ownValue(instrumentCurrency, id)).includes(key));
+}
+//# sourceMappingURL=rebalance.js.map