@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/monitor.js

@@ -0,0 +1,1806 @@
+/**
+ * `monitorPortfolio` (FC7 slice 4, Stage 4.4; agent-native "Monitoring and alerts"): evaluate ONE
+ * explicit valuation — a portfolio state, a market snapshot, an instant — against the investment
+ * policy and the PRIOR monitor state, and return typed alerts with evidence. It never sends a
+ * notification and never reads a clock: the host schedules evaluations, and a recorded stream of
+ * (market, portfolio, monitor-state) inputs reproduces the same alerts (the replay law, tested).
+ *
+ * Decisions this module executes:
+ *
+ * - **No secret defaults for goals.** A family evaluates only when the policy (or an explicit
+ *   caller rule) declares its limit; otherwise the family is reported `skipped` with the reason.
+ *   Rule MECHANICS (debounce 1, cooldown 0, per-family direction and severity) are defaults and
+ *   are echoed in `assumptions.rulesApplied`.
+ * - **A missing mark is an alert, not a crash.** When a held instrument has no usable spot the
+ *   portfolio cannot be valued: `stale-market-data` is raised for every such instrument, the
+ *   weight-based families are skipped as `unvalued`, and the cash-only families (cash reserve by
+ *   absolute amount, margin pressure) still evaluate from a cash-only valuation.
+ * - **The state machine is per (family, key)**: a breach enters at `enter` (or the threshold) and
+ *   clears past `exit`; `debounceEvaluations` consecutive breaches are needed before raising;
+ *   `cooldownMs` after the last raise suppresses a re-raise (reported as `suppressed`); an
+ *   acknowledged active rule reports `acknowledged` until it clears, and clearing emits `cleared`
+ *   exactly once. A subject that vanishes (a closed position, a removed target) clears.
+ * - **Skipped families carry their prior state forward untouched** — unknown is not cleared.
+ * - **Exposure is NOTIONAL; NAV is what is owned** (slice 5). The weight-based families
+ *   (allocation drift, concentration, leverage) measure `baseCurrencyNotionalValue` — quantity ×
+ *   mark × contract multiplier — over NAV. For a cash-on-trade position that is its market value;
+ *   for a variation-margin position (futures, perpetuals) NAV carries only the UNSETTLED P&L, so a
+ *   futures overlay's drift, concentration, and leverage are its notional, never its margin
+ *   balance. Drawdown, daily loss, and the cash families stay on `netAssetValue`.
+ *
+ * Families (in `MONITOR_ALERT_FAMILIES` order): `allocation-drift` (|current − target| per
+ * target, on notional weights), `concentration-limit` (|notional weight| per instrument and per
+ * group limit), `leverage-limit` (Σ|notional| ÷ NAV), `drawdown` (1 − NAV ÷ peak), `daily-loss`,
+ * `cash-reserve`, `margin-pressure` (settled base cash), `liquidity` (days to liquidate by
+ * quantity), `option-expiration` (days to expiry of every option position, direction below,
+ * against `optionExpirationWarningDays`), `assignment-risk` (moneyness of every SHORT option at
+ * the underlying's mark, direction above, against `assignmentRiskMoneyness`), `stale-market-data`,
+ * `reconciliation-difference`, `unexplained-residual`, `unusual-pnl`. Deferred (named in
+ * `diagnostics.unsupportedFamilies`): dividend risk (no ex-dividend calendar in this build),
+ * order status (the execution journal), scenario-loss change (Gate D).
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, requireArgumentArray, requireArgumentObject, requireRepresentableResult, resolveAsOf, stableSum, } from '../../core/dist/index.js';
+import { canonicalJsonOf, readMarketSnapshot } from '../../core/dist/artifacts/index.js';
+import { convertWithQuotes, deepFreeze, epochMsToUtcDate, ownValue, requireCurrencyPairQuoteShape, requireEpochMsField, requireFiniteNumberField, requireIdentityString, requirePositiveNumberField, setOwnValue, } from './internal.js';
+import { requireInstrumentClassification } from './pnl.js';
+import { expandTargets, isCashTargetGroup, requireInvestmentPolicy, resolvePolicyTargets, targetGroupKey, } from './policy-grammar.js';
+import { portfolioSnapshot } from './snapshot.js';
+import { requirePortfolioStateShape } from './state.js';
+export const PORTFOLIO_MONITOR_STATE_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------------------------------
+export const MONITOR_ALERT_FAMILIES = [
+    'allocation-drift',
+    'concentration-limit',
+    'leverage-limit',
+    'drawdown',
+    'daily-loss',
+    'cash-reserve',
+    'margin-pressure',
+    'liquidity',
+    'option-expiration',
+    'assignment-risk',
+    'stale-market-data',
+    'reconciliation-difference',
+    'unexplained-residual',
+    'unusual-pnl',
+];
+const FAMILY_DIRECTION = {
+    'allocation-drift': 'above',
+    'concentration-limit': 'above',
+    'leverage-limit': 'above',
+    drawdown: 'above',
+    'daily-loss': 'above',
+    'cash-reserve': 'below',
+    'margin-pressure': 'below',
+    liquidity: 'above',
+    'option-expiration': 'below',
+    'assignment-risk': 'above',
+    'stale-market-data': 'above',
+    'reconciliation-difference': 'above',
+    'unexplained-residual': 'above',
+    'unusual-pnl': 'above',
+};
+const FAMILY_SEVERITY = {
+    'allocation-drift': 'warning',
+    'concentration-limit': 'warning',
+    'leverage-limit': 'critical',
+    drawdown: 'critical',
+    'daily-loss': 'critical',
+    'cash-reserve': 'warning',
+    'margin-pressure': 'critical',
+    liquidity: 'warning',
+    'option-expiration': 'warning',
+    'assignment-risk': 'warning',
+    'stale-market-data': 'warning',
+    'reconciliation-difference': 'warning',
+    'unexplained-residual': 'warning',
+    'unusual-pnl': 'warning',
+};
+const DEFERRED_FAMILIES = [
+    {
+        family: 'dividend-risk',
+        reason: 'no ex-dividend calendar in this build — early-assignment risk around an ex-date needs one (expiry and moneyness ARE evaluated: see the option-expiration and assignment-risk families)',
+    },
+    {
+        family: 'order-status',
+        reason: 'no order journal in this build — orders live in the execution journal, not the ledger (Permanent law 3)',
+    },
+    {
+        family: 'scenario-loss-change',
+        reason: 'no scenario runner in this build (Gate D)',
+    },
+];
+/** Days to liquidate = |quantity| ÷ (averageDailyVolume × this rate). Stated in assumptions. */
+export const MONITOR_LIQUIDITY_PARTICIPATION_RATE = 0.1;
+/** Days to expiry = (expiryTimestampMs − asOf) ÷ this. */
+const MS_PER_DAY = 86_400_000;
+const INPUT_KEYS = [
+    'portfolio',
+    'market',
+    'asOf',
+    'currencyConversions',
+    'policy',
+    'instrumentClassification',
+    'previousState',
+    'rules',
+    'acknowledgments',
+    'reconciliation',
+    'pnl',
+    'averageDailyVolumes',
+    'marketStalenessLimitMs',
+    'unusualPnlThreshold',
+    'residualTolerance',
+    'optionExpirationWarningDays',
+    'assignmentRiskMoneyness',
+];
+const RULE_KEYS = [
+    'enabled',
+    'threshold',
+    'direction',
+    'hysteresis',
+    'debounceEvaluations',
+    'cooldownMs',
+    'severity',
+];
+const HYSTERESIS_KEYS = ['enter', 'exit'];
+const STATE_KEYS = [
+    'schemaVersion',
+    'asOf',
+    'netAssetValue',
+    'peakNetAssetValue',
+    'evaluationCount',
+    'rules',
+];
+const RULE_STATE_KEYS = [
+    'active',
+    'consecutiveBreaches',
+    'lastRaisedAtMs',
+    'acknowledged',
+    'lastValue',
+];
+const RECONCILIATION_KEYS = [
+    'asOf',
+    'baseCurrency',
+    'reconciled',
+    'accounts',
+    'differenceCount',
+    'explainedCount',
+    'suggestedCorrections',
+    'undraftable',
+    'assumptions',
+    'diagnostics',
+];
+const PNL_KEYS = [
+    'baseCurrency',
+    'from',
+    'to',
+    'netAssetValueChange',
+    'externalFlows',
+    'investmentReturn',
+    'components',
+    'residual',
+    'byCurrency',
+    'groupings',
+    'assumptions',
+    'diagnostics',
+];
+const DIRECTIONS = ['above', 'below'];
+const SEVERITIES = ['informational', 'warning', 'critical'];
+const CONVENTIONS = 'One evaluation values the portfolio with portfolioSnapshot at asOf (positions at ' +
+    'observations.spots, cash at face, base-currency conversion at the supplied quotes). Weights ' +
+    'are base-currency NOTIONAL value ÷ NAV (signed), notional = quantity × mark × contract ' +
+    'multiplier: for a cash-on-trade position that is its market value; for a variation-margin ' +
+    'position (futures, perpetuals) NAV carries only the unsettled P&L, so a futures overlay’s ' +
+    'drift, concentration, and leverage measure its notional, never its margin balance. An ' +
+    'instrument’s concentration is its absolute weight; a group’s is the absolute sum of its ' +
+    'members’ signed weights, members resolved by the policy grammar (instrumentId, sleeve tree, ' +
+    'classification, currency). Drift is |current − target| per instrument target and per group ' +
+    'target (the cash target compares the cash weight, cash ÷ NAV). Gross leverage is Σ|notional| ' +
+    '÷ NAV. Drawdown is 1 − NAV ÷ peak, the peak carried in the monitor state and initialised at ' +
+    'the first valued NAV (the current NAV joins the peak before the drawdown is measured). Daily ' +
+    'loss is (previous NAV − NAV) ÷ previous NAV between consecutive evaluations. The cash reserve ' +
+    'compares base-currency cash with the larger of minimumCash and minimumCashWeight × NAV; ' +
+    'margin pressure compares settled cash across all currencies converted to base. Days to ' +
+    'liquidate = |quantity| ÷ (averageDailyVolume × participation rate). Days to expiry = ' +
+    '(contract.expiryTimestampMs − asOf) ÷ 86,400,000 for every option position (negative once ' +
+    'past expiry), compared below optionExpirationWarningDays. Assignment risk is the moneyness of ' +
+    'every SHORT option at its underlying’s mark S against its strike K — call (S − K) ÷ K, put ' +
+    '(K − S) ÷ K, positive in the money — compared above assignmentRiskMoneyness; a short option ' +
+    'whose underlying has no usable mark (missing, no currency, or another currency) is raised ' +
+    'unconditionally with a null value. A mark’s age is asOf − (spot.timestampMs, else the ' +
+    'snapshot asOf); a held instrument without a usable spot is raised unconditionally and leaves ' +
+    'the portfolio unvalued (weight-based families skipped, cash-only and contract-term families ' +
+    'still evaluated). A breach is value > threshold (direction above) or value < threshold ' +
+    '(below); with hysteresis the rule enters past enter and clears past exit; debounce counts ' +
+    'consecutive breaching evaluations before raising; cooldown suppresses a re-raise within the ' +
+    'window after the last raise; acknowledgment holds until the rule clears. Families the policy ' +
+    'declares no limit for are skipped, never defaulted; skipped families carry their prior state ' +
+    'forward untouched.';
+const EXAMPLE_CALL = "monitorPortfolio({ portfolio: ledger.state, market, asOf: '2026-08-20', policy: { limits: { maximumPositionWeight: 0.25, maximumDrawdown: 0.1 } }, previousState: null })";
+// ---------------------------------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------------------------------
+function outOfRange(functionName, field, message) {
+    throw new InputError(`${functionName}: ${message}`, {
+        code: ErrorCode.InputOutOfRange,
+        context: { function: functionName, field },
+    });
+}
+function missingField(functionName, field, message) {
+    throw new InputError(`${functionName}: ${message}`, {
+        code: ErrorCode.InputMissingField,
+        context: { function: functionName, field },
+    });
+}
+function wrongType(functionName, field, message) {
+    throw new InputError(`${functionName}: ${message}`, {
+        code: ErrorCode.InputWrongType,
+        context: { function: functionName, field },
+    });
+}
+function received(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    return Array.isArray(value) ? 'array' : typeof value;
+}
+function requireLiteral(functionName, field, value, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new InputError(`${functionName}: ${field} must be one of ${allowed.map((v) => `'${v}'`).join(', ')}. Received ${received(value)}.`, {
+            code: typeof value === 'string' ? ErrorCode.InputOutOfRange : ErrorCode.InputWrongType,
+            context: { function: functionName, field },
+        });
+    }
+    return value;
+}
+function requireBoolean(functionName, field, value) {
+    if (typeof value !== 'boolean') {
+        wrongType(functionName, field, `${field} must be true or false. Received ${received(value)}.`);
+    }
+    return value;
+}
+function requireNonNegative(functionName, field, value) {
+    requireFiniteNumberField(functionName, field, value);
+    if (value < 0)
+        outOfRange(functionName, field, `${field} must be ≥ 0. Received ${value}.`);
+    return value;
+}
+function requireSafeIntegerAtLeast(functionName, field, value, minimum) {
+    requireFiniteNumberField(functionName, field, value);
+    if (!Number.isSafeInteger(value) || value < minimum) {
+        outOfRange(functionName, field, `${field} must be a safe integer ≥ ${minimum}. Received ${value}.`);
+    }
+    return value;
+}
+function requireFiniteOrNull(functionName, field, value) {
+    if (value === null)
+        return null;
+    requireFiniteNumberField(functionName, field, value);
+    return value;
+}
+/** Six significant digits for prose; evidence keeps full precision. */
+function pretty(value) {
+    if (value === null)
+        return 'null';
+    return String(Number(value.toPrecision(6)));
+}
+function compareKeys(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** The family of a `'family:key'` rule identity — the prefix up to the first colon. */
+function familyOfKey(key) {
+    const colon = key.indexOf(':');
+    if (colon <= 0)
+        return null;
+    const family = key.slice(0, colon);
+    return MONITOR_ALERT_FAMILIES.includes(family)
+        ? family
+        : null;
+}
+// ---------------------------------------------------------------------------------------------------
+// Validation — rules, prior state, companion results
+// ---------------------------------------------------------------------------------------------------
+function requireHysteresis(functionName, path, value, direction) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, HYSTERESIS_KEYS);
+    const raw = value;
+    for (const field of HYSTERESIS_KEYS) {
+        if (raw[field] === undefined) {
+            missingField(functionName, `${path}.${field}`, `${path}.${field} is required — hysteresis is an enter/exit pair.\n  e.g. hysteresis: { enter: 0.05, exit: 0.02 }`);
+        }
+        requireFiniteNumberField(functionName, `${path}.${field}`, raw[field]);
+    }
+    const enter = raw['enter'];
+    const exit = raw['exit'];
+    if (direction === 'above' && exit > enter) {
+        outOfRange(functionName, `${path}.exit`, `${path}.exit (${exit}) must be ≤ enter (${enter}) for direction 'above' — the rule enters past enter and clears back past exit.`);
+    }
+    if (direction === 'below' && exit < enter) {
+        outOfRange(functionName, `${path}.exit`, `${path}.exit (${exit}) must be ≥ enter (${enter}) for direction 'below' — the rule enters past enter and clears back past exit.`);
+    }
+    return { enter, exit };
+}
+function requireMonitorRules(functionName, value) {
+    if (value === undefined)
+        return {};
+    requireArgumentObject(functionName, 'rules', value);
+    ensureKnownKeys(functionName, 'rules', value, MONITOR_ALERT_FAMILIES);
+    const raw = value;
+    const out = {};
+    for (const family of MONITOR_ALERT_FAMILIES) {
+        const entry = ownValue(raw, family);
+        if (entry === undefined)
+            continue;
+        const path = `rules['${family}']`;
+        requireArgumentObject(functionName, path, entry);
+        ensureKnownKeys(functionName, path, entry, RULE_KEYS);
+        const rule = entry;
+        const cleaned = {};
+        if (rule['enabled'] !== undefined) {
+            cleaned.enabled = requireBoolean(functionName, `${path}.enabled`, rule['enabled']);
+        }
+        if (rule['direction'] !== undefined) {
+            cleaned.direction = requireLiteral(functionName, `${path}.direction`, rule['direction'], DIRECTIONS);
+        }
+        const direction = cleaned.direction ?? FAMILY_DIRECTION[family];
+        if (rule['threshold'] !== undefined && rule['hysteresis'] !== undefined) {
+            outOfRange(functionName, `${path}.threshold`, `${path} declares both threshold and hysteresis — hysteresis.enter IS the threshold; give one or the other.`);
+        }
+        if (rule['threshold'] !== undefined) {
+            requireFiniteNumberField(functionName, `${path}.threshold`, rule['threshold']);
+            cleaned.threshold = rule['threshold'];
+        }
+        if (rule['hysteresis'] !== undefined) {
+            cleaned.hysteresis = requireHysteresis(functionName, `${path}.hysteresis`, rule['hysteresis'], direction);
+        }
+        if (rule['debounceEvaluations'] !== undefined) {
+            cleaned.debounceEvaluations = requireSafeIntegerAtLeast(functionName, `${path}.debounceEvaluations`, rule['debounceEvaluations'], 1);
+        }
+        if (rule['cooldownMs'] !== undefined) {
+            cleaned.cooldownMs = requireNonNegative(functionName, `${path}.cooldownMs`, rule['cooldownMs']);
+        }
+        if (rule['severity'] !== undefined) {
+            cleaned.severity = requireLiteral(functionName, `${path}.severity`, rule['severity'], SEVERITIES);
+        }
+        setOwnValue(out, family, cleaned);
+    }
+    return out;
+}
+function requirePreviousMonitorState(functionName, value, asOf) {
+    requireArgumentObject(functionName, 'previousState', value);
+    ensureKnownKeys(functionName, 'previousState', value, STATE_KEYS);
+    const raw = value;
+    if (raw['schemaVersion'] !== PORTFOLIO_MONITOR_STATE_SCHEMA_VERSION) {
+        throw new InputError(`${functionName}: previousState.schemaVersion must be ${PORTFOLIO_MONITOR_STATE_SCHEMA_VERSION} — pass the state returned by the prior monitorPortfolio call of this build. Received ${received(raw['schemaVersion'])}.`, {
+            code: ErrorCode.SnapshotUnsupportedVersion,
+            context: { function: functionName, field: 'previousState.schemaVersion' },
+        });
+    }
+    requireEpochMsField(functionName, 'previousState.asOf', raw['asOf']);
+    const previousAsOf = raw['asOf'];
+    if (previousAsOf >= asOf) {
+        outOfRange(functionName, 'previousState.asOf', `previousState.asOf (${previousAsOf}, ${epochMsToUtcDate(previousAsOf)}) must be before asOf (${asOf}, ${epochMsToUtcDate(asOf)}) — evaluations move forward in time; replaying an instant is a re-run from the state BEFORE it.`);
+    }
+    const netAssetValue = requireFiniteOrNull(functionName, 'previousState.netAssetValue', raw['netAssetValue']);
+    const peakNetAssetValue = requireFiniteOrNull(functionName, 'previousState.peakNetAssetValue', raw['peakNetAssetValue']);
+    if (netAssetValue !== null && peakNetAssetValue === null) {
+        outOfRange(functionName, 'previousState.peakNetAssetValue', `previousState.peakNetAssetValue is null while netAssetValue is ${netAssetValue} — a valued evaluation always records its peak; this state was edited by hand.`);
+    }
+    if (netAssetValue !== null && peakNetAssetValue !== null && peakNetAssetValue < netAssetValue) {
+        outOfRange(functionName, 'previousState.peakNetAssetValue', `previousState.peakNetAssetValue (${peakNetAssetValue}) must be ≥ netAssetValue (${netAssetValue}) — the peak includes the evaluation's own NAV.`);
+    }
+    const evaluationCount = requireSafeIntegerAtLeast(functionName, 'previousState.evaluationCount', raw['evaluationCount'], 1);
+    requireArgumentObject(functionName, 'previousState.rules', raw['rules']);
+    const rules = {};
+    for (const key of Object.keys(raw['rules']).sort(compareKeys)) {
+        const path = `previousState.rules['${key}']`;
+        if (familyOfKey(key) === null) {
+            outOfRange(functionName, path, `${path} is not a '<family>:<key>' rule identity of this build (families: ${MONITOR_ALERT_FAMILIES.join(', ')}).`);
+        }
+        const entry = ownValue(raw['rules'], key);
+        requireArgumentObject(functionName, path, entry);
+        ensureKnownKeys(functionName, path, entry, RULE_STATE_KEYS);
+        const record = entry;
+        const lastRaisedAtMs = record['lastRaisedAtMs'];
+        if (lastRaisedAtMs !== null) {
+            requireEpochMsField(functionName, `${path}.lastRaisedAtMs`, lastRaisedAtMs);
+        }
+        setOwnValue(rules, key, {
+            active: requireBoolean(functionName, `${path}.active`, record['active']),
+            consecutiveBreaches: requireSafeIntegerAtLeast(functionName, `${path}.consecutiveBreaches`, record['consecutiveBreaches'], 0),
+            lastRaisedAtMs: lastRaisedAtMs,
+            acknowledged: requireBoolean(functionName, `${path}.acknowledged`, record['acknowledged']),
+            lastValue: requireFiniteOrNull(functionName, `${path}.lastValue`, record['lastValue']),
+        });
+    }
+    return {
+        schemaVersion: PORTFOLIO_MONITOR_STATE_SCHEMA_VERSION,
+        asOf: previousAsOf,
+        netAssetValue,
+        peakNetAssetValue,
+        evaluationCount,
+        rules,
+    };
+}
+function requireAcknowledgments(functionName, value) {
+    if (value === undefined)
+        return [];
+    requireArgumentArray(functionName, 'acknowledgments', value);
+    const out = new Set();
+    value.forEach((entry, index) => {
+        requireIdentityString(functionName, `acknowledgments[${index}]`, entry);
+        out.add(entry);
+    });
+    return [...out].sort(compareKeys);
+}
+function requireReconciliationResult(functionName, value, baseCurrency, asOf) {
+    requireArgumentObject(functionName, 'reconciliation', value);
+    ensureKnownKeys(functionName, 'reconciliation', value, RECONCILIATION_KEYS);
+    const raw = value;
+    requireEpochMsField(functionName, 'reconciliation.asOf', raw['asOf']);
+    if (raw['asOf'] > asOf) {
+        outOfRange(functionName, 'reconciliation.asOf', `reconciliation.asOf (${epochMsToUtcDate(raw['asOf'])}) is after asOf (${epochMsToUtcDate(asOf)}) — a monitor evaluates evidence at or before its instant.`);
+    }
+    if (raw['baseCurrency'] !== baseCurrency) {
+        outOfRange(functionName, 'reconciliation.baseCurrency', `reconciliation.baseCurrency (${received(raw['baseCurrency'])}) must equal the portfolio's base currency (${baseCurrency}) — pass the reconcilePortfolio result for THIS portfolio.`);
+    }
+    const reconciled = requireBoolean(functionName, 'reconciliation.reconciled', raw['reconciled']);
+    const differenceCount = requireSafeIntegerAtLeast(functionName, 'reconciliation.differenceCount', raw['differenceCount'], 0);
+    const explainedCount = requireSafeIntegerAtLeast(functionName, 'reconciliation.explainedCount', raw['explainedCount'], 0);
+    if (explainedCount > differenceCount || reconciled !== (differenceCount === explainedCount)) {
+        outOfRange(functionName, 'reconciliation.reconciled', `reconciliation.reconciled (${reconciled}) disagrees with its counts (differenceCount ${differenceCount}, explainedCount ${explainedCount}) — reconcilePortfolio defines reconciled as differenceCount === explainedCount; this result was edited.`);
+    }
+    requireArgumentArray(functionName, 'reconciliation.suggestedCorrections', raw['suggestedCorrections']);
+    return value;
+}
+function requirePnlResult(functionName, value, baseCurrency, asOf) {
+    requireArgumentObject(functionName, 'pnl', value);
+    ensureKnownKeys(functionName, 'pnl', value, PNL_KEYS);
+    const raw = value;
+    if (raw['baseCurrency'] !== baseCurrency) {
+        outOfRange(functionName, 'pnl.baseCurrency', `pnl.baseCurrency (${received(raw['baseCurrency'])}) must equal the portfolio's base currency (${baseCurrency}) — pass the portfolioPnl result for THIS portfolio.`);
+    }
+    for (const end of ['from', 'to']) {
+        requireArgumentObject(functionName, `pnl.${end}`, raw[end]);
+        const mark = raw[end];
+        requireEpochMsField(functionName, `pnl.${end}.asOf`, mark['asOf']);
+        requireFiniteNumberField(functionName, `pnl.${end}.netAssetValue`, mark['netAssetValue']);
+    }
+    const fromAsOf = raw['from']['asOf'];
+    const toAsOf = raw['to']['asOf'];
+    if (toAsOf <= fromAsOf) {
+        outOfRange(functionName, 'pnl.to.asOf', `pnl.to.asOf (${epochMsToUtcDate(toAsOf)}) must be after pnl.from.asOf (${epochMsToUtcDate(fromAsOf)}).`);
+    }
+    if (toAsOf > asOf) {
+        outOfRange(functionName, 'pnl.to.asOf', `pnl.to.asOf (${epochMsToUtcDate(toAsOf)}) is after asOf (${epochMsToUtcDate(asOf)}) — a monitor evaluates evidence at or before its instant.`);
+    }
+    requireFiniteNumberField(functionName, 'pnl.residual', raw['residual']);
+    requireFiniteNumberField(functionName, 'pnl.investmentReturn', raw['investmentReturn']);
+    requireArgumentObject(functionName, 'pnl.components', raw['components']);
+    requireFiniteNumberField(functionName, 'pnl.components.totalPnl', raw['components']['totalPnl']);
+    return value;
+}
+function requireAverageDailyVolumes(functionName, value) {
+    if (value === undefined)
+        return undefined;
+    requireArgumentObject(functionName, 'averageDailyVolumes', value);
+    const raw = value;
+    const out = {};
+    for (const instrumentId of Object.keys(raw).sort(compareKeys)) {
+        requireIdentityString(functionName, 'averageDailyVolumes key', instrumentId);
+        const path = `averageDailyVolumes['${instrumentId}']`;
+        const volume = ownValue(raw, instrumentId);
+        requirePositiveNumberField(functionName, path, volume, 'units traded per day');
+        setOwnValue(out, instrumentId, volume);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------------------------------
+// Rule resolution and the state machine
+// ---------------------------------------------------------------------------------------------------
+function resolveRule(family, override, declared) {
+    const hysteresis = override?.hysteresis ?? null;
+    const ruleThreshold = override?.threshold;
+    const threshold = hysteresis !== null ? hysteresis.enter : (ruleThreshold ?? declared.threshold);
+    const thresholdSource = hysteresis !== null || ruleThreshold !== undefined ? 'rule' : declared.source;
+    return {
+        enabled: override?.enabled ?? true,
+        threshold,
+        thresholdSource,
+        direction: override?.direction ?? FAMILY_DIRECTION[family],
+        hysteresis: hysteresis === null ? null : { enter: hysteresis.enter, exit: hysteresis.exit },
+        debounceEvaluations: override?.debounceEvaluations ?? 1,
+        cooldownMs: override?.cooldownMs ?? 0,
+        severity: override?.severity ?? FAMILY_SEVERITY[family],
+    };
+}
+const FRESH_RULE_STATE = {
+    active: false,
+    consecutiveBreaches: 0,
+    lastRaisedAtMs: null,
+    acknowledged: false,
+    lastValue: null,
+};
+function transition(prior, rule, observation, asOf, acknowledgedNow) {
+    const before = prior ?? FRESH_RULE_STATE;
+    const bound = rule.hysteresis !== null
+        ? before.active
+            ? rule.hysteresis.exit
+            : rule.hysteresis.enter
+        : (rule.threshold ?? observation.threshold);
+    let breach;
+    if (observation.forcedBreach) {
+        breach = true;
+    }
+    else if (observation.value === null || bound === null) {
+        // Not computable: unknown is neither a breach nor a clear — the prior state is carried.
+        return { next: prior ?? null, alertState: null, bound, computable: false };
+    }
+    else {
+        breach = rule.direction === 'above' ? observation.value > bound : observation.value < bound;
+    }
+    const lastValue = observation.value;
+    if (breach) {
+        const consecutiveBreaches = before.consecutiveBreaches + 1;
+        if (before.active) {
+            const acknowledged = before.acknowledged || acknowledgedNow;
+            return {
+                next: {
+                    active: true,
+                    consecutiveBreaches,
+                    lastRaisedAtMs: before.lastRaisedAtMs,
+                    acknowledged,
+                    lastValue,
+                },
+                alertState: acknowledged ? 'acknowledged' : 'active',
+                bound,
+                computable: true,
+            };
+        }
+        if (consecutiveBreaches < rule.debounceEvaluations) {
+            return {
+                next: { ...before, consecutiveBreaches, lastValue },
+                alertState: null,
+                bound,
+                computable: true,
+            };
+        }
+        if (before.lastRaisedAtMs !== null && asOf - before.lastRaisedAtMs < rule.cooldownMs) {
+            return {
+                next: { ...before, consecutiveBreaches, lastValue },
+                alertState: 'suppressed',
+                bound,
+                computable: true,
+            };
+        }
+        return {
+            next: {
+                active: true,
+                consecutiveBreaches,
+                lastRaisedAtMs: asOf,
+                acknowledged: false,
+                lastValue,
+            },
+            alertState: 'raised',
+            bound,
+            computable: true,
+        };
+    }
+    if (before.active) {
+        return {
+            next: {
+                active: false,
+                consecutiveBreaches: 0,
+                lastRaisedAtMs: before.lastRaisedAtMs,
+                acknowledged: false,
+                lastValue,
+            },
+            alertState: 'cleared',
+            bound,
+            computable: true,
+        };
+    }
+    return {
+        next: { ...before, consecutiveBreaches: 0, lastValue },
+        alertState: null,
+        bound,
+        computable: true,
+    };
+}
+/**
+ * Held instruments aggregated across accounts, sorted by instrument id. The fold guarantees one
+ * profile per open position within an account; across accounts a disagreement (the same
+ * instrument id with different terms) is reported as a warning and the first account's profile is
+ * used — the contract-term families never guess between two sets of terms.
+ */
+function aggregateHoldings(state, warnings) {
+    const byInstrument = new Map();
+    for (const accountId of Object.keys(state.accounts).sort(compareKeys)) {
+        const account = ownValue(state.accounts, accountId);
+        for (const instrumentId of Object.keys(account.positions).sort(compareKeys)) {
+            const position = ownValue(account.positions, instrumentId);
+            const existing = byInstrument.get(instrumentId);
+            if (existing === undefined) {
+                byInstrument.set(instrumentId, {
+                    instrumentId,
+                    currency: position.currency,
+                    quantity: position.quantity,
+                    accounts: [accountId],
+                    contractMultiplier: position.contractMultiplier,
+                    settlementStyle: position.settlementStyle,
+                    contract: position.contract ?? null,
+                });
+            }
+            else {
+                existing.quantity += position.quantity;
+                existing.accounts.push(accountId);
+                if (existing.contractMultiplier !== position.contractMultiplier ||
+                    existing.settlementStyle !== position.settlementStyle ||
+                    canonicalJsonOf(existing.contract) !== canonicalJsonOf(position.contract ?? null)) {
+                    warnings.push(`account '${accountId}' holds ${instrumentId} under a different instrument profile (multiplier, settlement style, or contract terms) from account '${existing.accounts[0]}' — the contract-term families use account '${existing.accounts[0]}''s profile; reconcile the instrument ids.`);
+                }
+            }
+        }
+    }
+    return [...byInstrument.values()].sort((a, b) => compareKeys(a.instrumentId, b.instrumentId));
+}
+/** A spot usable as the mark of `instrumentId` in `currency`, or the reason it is not. */
+function usableSpot(spots, instrumentId, currency) {
+    const spot = ownValue(spots, instrumentId);
+    if (spot === undefined) {
+        return {
+            price: null,
+            reason: `the market snapshot carries no observations.spots['${instrumentId}']`,
+        };
+    }
+    if (spot.currency === undefined) {
+        return {
+            price: null,
+            reason: `observations.spots['${instrumentId}'] states no currency (the position trades in ${currency})`,
+        };
+    }
+    if (spot.currency !== currency) {
+        return {
+            price: null,
+            reason: `observations.spots['${instrumentId}'] is quoted in ${spot.currency}, but the position trades in ${currency}`,
+        };
+    }
+    return { price: spot.price, reason: null };
+}
+/** The state with every position removed — cash values without marks. */
+function cashOnlyState(state) {
+    const accounts = {};
+    for (const accountId of Object.keys(state.accounts)) {
+        setOwnValue(accounts, accountId, { ...ownValue(state.accounts, accountId), positions: {} });
+    }
+    return { ...state, accounts };
+}
+// ---------------------------------------------------------------------------------------------------
+// The head
+// ---------------------------------------------------------------------------------------------------
+/**
+ * Evaluate one explicit valuation against the policy and the prior monitor state — see the module
+ * comment for the decisions. Pure: same inputs, same alerts and state.
+ *
+ * @example
+ * ```ts
+ * import { monitorPortfolio } from '@insiderfinance/totalfinance/portfolio/policy';
+ *
+ * const first = monitorPortfolio({
+ *   portfolio: ledger.state,
+ *   market,
+ *   asOf: '2026-08-20',
+ *   policy: { limits: { maximumPositionWeight: 0.25, maximumDrawdown: 0.1 } },
+ *   previousState: null,
+ * });
+ * const next = monitorPortfolio({ ...sameInputs, asOf: '2026-08-21', previousState: first.state });
+ * next.alerts; // [{ key: 'concentration-limit:AAPL', state: 'raised', value: 0.31, threshold: 0.25, … }]
+ * ```
+ */
+export function monitorPortfolio(input) {
+    const functionName = 'monitorPortfolio';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, INPUT_KEYS);
+    requirePortfolioStateShape(functionName, 'portfolio', input.portfolio);
+    if (input.asOf === undefined) {
+        missingField(functionName, 'asOf', `asOf is required — TotalFinance never reads the system clock, so the caller states the evaluation instant.\n  e.g. ${EXAMPLE_CALL}`);
+    }
+    const asOf = resolveAsOf(input.asOf, functionName);
+    requireEpochMsField(functionName, 'asOf', asOf);
+    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);
+        });
+    }
+    if (input.policy === undefined) {
+        missingField(functionName, 'policy', `policy is required — a monitor evaluates the caller's explicit goals; without a policy nothing is measured.\n  e.g. ${EXAMPLE_CALL}`);
+    }
+    const policy = requireInvestmentPolicy(functionName, 'policy', input.policy);
+    const classification = requireInstrumentClassification(functionName, input.instrumentClassification);
+    if (input.previousState === undefined) {
+        missingField(functionName, 'previousState', `previousState is required — pass the prior evaluation's state, or null for the FIRST evaluation. An omitted key would silently reset hysteresis, debounce, cooldown, acknowledgments, and the drawdown peak.\n  e.g. ${EXAMPLE_CALL}`);
+    }
+    const previous = input.previousState === null
+        ? null
+        : requirePreviousMonitorState(functionName, input.previousState, asOf);
+    const overrides = requireMonitorRules(functionName, input.rules);
+    const acknowledgments = requireAcknowledgments(functionName, input.acknowledgments);
+    const state = input.portfolio;
+    const baseCurrency = state.baseCurrency;
+    const reconciliation = input.reconciliation === undefined
+        ? undefined
+        : requireReconciliationResult(functionName, input.reconciliation, baseCurrency, asOf);
+    const pnl = input.pnl === undefined
+        ? undefined
+        : requirePnlResult(functionName, input.pnl, baseCurrency, asOf);
+    const volumes = requireAverageDailyVolumes(functionName, input.averageDailyVolumes);
+    const stalenessLimitMs = input.marketStalenessLimitMs === undefined
+        ? undefined
+        : requireNonNegative(functionName, 'marketStalenessLimitMs', input.marketStalenessLimitMs);
+    const unusualPnlThreshold = input.unusualPnlThreshold === undefined
+        ? undefined
+        : requireNonNegative(functionName, 'unusualPnlThreshold', input.unusualPnlThreshold);
+    const residualTolerance = input.residualTolerance === undefined
+        ? undefined
+        : requireNonNegative(functionName, 'residualTolerance', input.residualTolerance);
+    const optionExpirationWarningDays = input.optionExpirationWarningDays === undefined
+        ? undefined
+        : requireNonNegative(functionName, 'optionExpirationWarningDays', input.optionExpirationWarningDays);
+    let assignmentRiskMoneyness;
+    if (input.assignmentRiskMoneyness !== undefined) {
+        requireFiniteNumberField(functionName, 'assignmentRiskMoneyness', input.assignmentRiskMoneyness);
+        assignmentRiskMoneyness = input.assignmentRiskMoneyness;
+    }
+    const warnings = [];
+    const limits = policy.limits ?? {};
+    // ---- rules: defaults + policy limits + overrides ----
+    const declaredThreshold = (value, source) => value === undefined ? { threshold: null, source: 'none' } : { threshold: value, source };
+    const rules = {
+        'allocation-drift': resolveRule('allocation-drift', overrides['allocation-drift'], {
+            threshold: null,
+            source: 'per-observation',
+        }),
+        'concentration-limit': resolveRule('concentration-limit', overrides['concentration-limit'], declaredThreshold(limits.maximumPositionWeight, 'policy')),
+        'leverage-limit': resolveRule('leverage-limit', overrides['leverage-limit'], declaredThreshold(limits.maximumGrossLeverage, 'policy')),
+        drawdown: resolveRule('drawdown', overrides['drawdown'], declaredThreshold(limits.maximumDrawdown, 'policy')),
+        'daily-loss': resolveRule('daily-loss', overrides['daily-loss'], declaredThreshold(limits.maximumDailyLoss, 'policy')),
+        'cash-reserve': resolveRule('cash-reserve', overrides['cash-reserve'], {
+            threshold: null,
+            source: policy.minimumCash !== undefined || policy.minimumCashWeight !== undefined
+                ? 'policy'
+                : 'none',
+        }),
+        'margin-pressure': resolveRule('margin-pressure', overrides['margin-pressure'], declaredThreshold(limits.minimumSettledCash, 'policy')),
+        liquidity: resolveRule('liquidity', overrides['liquidity'], declaredThreshold(limits.maximumDaysToLiquidate, 'policy')),
+        'option-expiration': resolveRule('option-expiration', overrides['option-expiration'], declaredThreshold(optionExpirationWarningDays, 'input')),
+        'assignment-risk': resolveRule('assignment-risk', overrides['assignment-risk'], declaredThreshold(assignmentRiskMoneyness, 'input')),
+        'stale-market-data': resolveRule('stale-market-data', overrides['stale-market-data'], declaredThreshold(stalenessLimitMs, 'input')),
+        'reconciliation-difference': resolveRule('reconciliation-difference', overrides['reconciliation-difference'], { threshold: 0, source: 'input' }),
+        'unexplained-residual': resolveRule('unexplained-residual', overrides['unexplained-residual'], declaredThreshold(residualTolerance, 'input')),
+        'unusual-pnl': resolveRule('unusual-pnl', overrides['unusual-pnl'], declaredThreshold(unusualPnlThreshold, 'input')),
+    };
+    const ruleDeclaresThreshold = (family) => rules[family].thresholdSource === 'rule';
+    // ---- holdings and marks: which instruments can be valued ----
+    const holdings = aggregateHoldings(state, warnings);
+    const spots = market.observations.spots ?? {};
+    const unusable = new Map();
+    for (const holding of holdings) {
+        const { reason } = usableSpot(spots, holding.instrumentId, holding.currency);
+        if (reason !== null)
+            unusable.set(holding.instrumentId, reason);
+    }
+    const snapshotInput = {
+        asOf,
+        market: input.market,
+        ...(input.currencyConversions !== undefined
+            ? { currencyConversions: input.currencyConversions }
+            : {}),
+    };
+    let valued = null;
+    let cashRows;
+    let totalCash;
+    if (unusable.size === 0) {
+        valued = portfolioSnapshot({ portfolio: state, ...snapshotInput });
+        cashRows = valued.cash;
+        totalCash = valued.totalCashBaseCurrencyValue;
+        warnings.push(...valued.diagnostics.warnings);
+    }
+    else {
+        // Marks are missing: value the cash side alone (it needs quotes, never marks) so the
+        // cash-only families still evaluate; the weight-based families are skipped as unvalued.
+        const cashOnly = portfolioSnapshot({ portfolio: cashOnlyState(state), ...snapshotInput });
+        cashRows = cashOnly.cash;
+        totalCash = cashOnly.totalCashBaseCurrencyValue;
+        warnings.push(...cashOnly.diagnostics.warnings);
+    }
+    const netAssetValue = valued === null ? null : valued.netAssetValue;
+    const unvaluedReason = unusable.size === 0
+        ? null
+        : `unvalued: ${unusable.size} held instrument${unusable.size === 1 ? '' : 's'} (${[...unusable.keys()].join(', ')}) ${unusable.size === 1 ? 'has' : 'have'} no usable mark — see the stale-market-data alerts`;
+    const navReason = netAssetValue !== null && netAssetValue <= 0
+        ? `net asset value ${netAssetValue} is not positive; weights of NAV are undefined`
+        : null;
+    // Per-instrument base-currency NOTIONAL (the exposure every weight is built on) and the NAV
+    // contribution (market value — the unsettled P&L for a variation-margin position), aggregated
+    // across accounts. Weights are signed notional ÷ NAV.
+    const notionalByInstrument = new Map();
+    const valueByInstrument = new Map();
+    if (valued !== null) {
+        for (const row of valued.positions) {
+            notionalByInstrument.set(row.instrumentId, (notionalByInstrument.get(row.instrumentId) ?? 0) + row.baseCurrencyNotionalValue);
+            valueByInstrument.set(row.instrumentId, (valueByInstrument.get(row.instrumentId) ?? 0) + row.baseCurrencyMarketValue);
+        }
+    }
+    const weightOf = (instrumentId) => netAssetValue === null || netAssetValue <= 0
+        ? 0
+        : (notionalByInstrument.get(instrumentId) ?? 0) / netAssetValue;
+    const cashWeight = netAssetValue === null || netAssetValue <= 0 ? 0 : totalCash / netAssetValue;
+    const currentWeights = {};
+    const instrumentCurrency = {};
+    for (const holding of holdings) {
+        setOwnValue(currentWeights, holding.instrumentId, weightOf(holding.instrumentId));
+        setOwnValue(instrumentCurrency, holding.instrumentId, holding.currency);
+    }
+    const universe = [
+        ...new Set([...holdings.map((h) => h.instrumentId), ...(policy.allowedInstruments ?? [])]),
+    ].sort(compareKeys);
+    const expansionInput = (targets) => ({
+        targets,
+        universe,
+        instrumentClassification: classification,
+        instrumentCurrency,
+        currentWeights,
+        sleeves: policy.model?.sleeves ?? [],
+        withinGroupAllocation: policy.withinGroupAllocation,
+        defaultDriftBand: policy.driftBand,
+    });
+    const declaredSleeves = new Set((policy.model?.sleeves ?? []).map((s) => s.sleeveId));
+    // Drawdown peak: the current NAV joins the peak before the drawdown is measured.
+    const priorPeak = previous?.peakNetAssetValue ?? null;
+    const peakNetAssetValue = netAssetValue === null
+        ? priorPeak
+        : priorPeak === null
+            ? netAssetValue
+            : Math.max(priorPeak, netAssetValue);
+    // ---- family evaluation ----
+    const evaluations = [];
+    const observations = new Map();
+    const skip = (family, reason) => {
+        evaluations.push({ family, status: 'skipped', observationCount: 0, reason });
+    };
+    const evaluate = (family, list) => {
+        const seen = new Set();
+        for (const observation of list) {
+            if (seen.has(observation.key)) {
+                outOfRange(functionName, 'portfolio', `${family} observed the key '${observation.key}' twice — an instrument id that spells like a group key ('<dimension>:<value>') collides with the group; rename the instrument or the group.`);
+            }
+            seen.add(observation.key);
+        }
+        observations.set(family, list);
+        evaluations.push({ family, status: 'evaluated', observationCount: list.length });
+    };
+    const gate = (family, needsValuation) => {
+        if (!rules[family].enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+            return false;
+        }
+        if (needsValuation && unvaluedReason !== null) {
+            skip(family, unvaluedReason);
+            return false;
+        }
+        if (needsValuation && navReason !== null) {
+            skip(family, navReason);
+            return false;
+        }
+        return true;
+    };
+    // allocation-drift
+    if (policy.targets === undefined && policy.model === undefined) {
+        if (rules['allocation-drift'].enabled) {
+            skip('allocation-drift', 'policy declares no targets (policy.targets or policy.model)');
+        }
+        else {
+            skip('allocation-drift', "rules['allocation-drift'].enabled is false");
+        }
+    }
+    else if (gate('allocation-drift', true)) {
+        const rule = rules['allocation-drift'];
+        const resolved = resolvePolicyTargets(functionName, policy, asOf);
+        const expanded = expandTargets(functionName, expansionInput(resolved.targets));
+        warnings.push(...expanded.warnings.map((w) => `allocation-drift: ${w}`));
+        for (const item of expanded.unresolved) {
+            warnings.push(`allocation-drift: target '${item.key}' is unresolved — ${item.reason}`);
+        }
+        const anyBand = expanded.instrumentTargets.some((t) => t.driftBand !== null) ||
+            expanded.groupTargets.some((g) => g.driftBand !== null) ||
+            (expanded.cashTarget?.driftBand ?? null) !== null;
+        if (!ruleDeclaresThreshold('allocation-drift') && !anyBand) {
+            skip('allocation-drift', 'policy declares no driftBand (and no target declares its own) — a band is the goal a drift alert measures against');
+        }
+        else {
+            const list = [];
+            const bandless = [];
+            const useHysteresis = rule.hysteresis !== null;
+            for (const target of expanded.instrumentTargets) {
+                const band = rule.threshold ?? target.driftBand;
+                if (band === null && !useHysteresis) {
+                    bandless.push(target.instrumentId);
+                    continue;
+                }
+                const current = weightOf(target.instrumentId);
+                const drift = Math.abs(current - target.targetWeight);
+                list.push({
+                    key: target.instrumentId,
+                    subject: `instrument ${target.instrumentId}`,
+                    value: drift,
+                    threshold: band,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `${target.instrumentId} weighs ${pretty(current)} of NAV against a target of ${pretty(target.targetWeight)} (drift ${pretty(drift)}, band ${pretty(band)})`,
+                    evidence: {
+                        currentWeight: current,
+                        targetWeight: target.targetWeight,
+                        drift,
+                        driftBand: band,
+                        sourceGroups: target.sourceGroups.length === 0 ? null : target.sourceGroups.join(', '),
+                        implied: target.implied ? 'yes' : 'no',
+                        targetSource: resolved.source,
+                    },
+                });
+            }
+            for (const group of expanded.groupTargets) {
+                // An instrumentId group IS the instrument target above; the cash target compares cash.
+                if (group.group.instrumentId !== undefined)
+                    continue;
+                const band = rule.threshold ?? group.driftBand;
+                if (band === null && !useHysteresis) {
+                    bandless.push(group.key);
+                    continue;
+                }
+                const current = isCashTargetGroup(group.group)
+                    ? cashWeight
+                    : stableSum(group.members.map((id) => weightOf(id)));
+                const drift = Math.abs(current - group.targetWeight);
+                list.push({
+                    key: group.key,
+                    subject: `group ${group.key}`,
+                    value: drift,
+                    threshold: band,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `group ${group.key} weighs ${pretty(current)} of NAV against a target of ${pretty(group.targetWeight)} (drift ${pretty(drift)}, band ${pretty(band)})`,
+                    evidence: {
+                        currentWeight: current,
+                        targetWeight: group.targetWeight,
+                        drift,
+                        driftBand: band,
+                        members: group.members.length === 0 ? null : group.members.join(', '),
+                        memberCount: group.members.length,
+                        targetSource: resolved.source,
+                    },
+                });
+            }
+            if (bandless.length > 0) {
+                warnings.push(`allocation-drift: no drift band for ${bandless.join(', ')} — declare policy.driftBand or a per-target driftBand to monitor ${bandless.length === 1 ? 'it' : 'them'}.`);
+            }
+            evaluate('allocation-drift', list);
+        }
+    }
+    // concentration-limit
+    {
+        const family = 'concentration-limit';
+        const groupLimits = limits.maximumGroupWeights ?? [];
+        if (limits.maximumPositionWeight === undefined &&
+            groupLimits.length === 0 &&
+            !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled) {
+                skip(family, 'policy declares no limits.maximumPositionWeight or limits.maximumGroupWeights');
+            }
+            else {
+                skip(family, `rules['${family}'].enabled is false`);
+            }
+        }
+        else if (gate(family, true)) {
+            const rule = rules[family];
+            const list = [];
+            const positionLimit = rule.threshold ?? limits.maximumPositionWeight ?? null;
+            if (positionLimit !== null || rule.hysteresis !== null) {
+                for (const holding of holdings) {
+                    const weight = weightOf(holding.instrumentId);
+                    const absolute = Math.abs(weight);
+                    list.push({
+                        key: holding.instrumentId,
+                        subject: `instrument ${holding.instrumentId}`,
+                        value: absolute,
+                        threshold: positionLimit,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `${holding.instrumentId} weighs ${pretty(absolute)} of NAV by notional against maximumPositionWeight ${pretty(positionLimit)}`,
+                        evidence: {
+                            weight,
+                            absoluteWeight: absolute,
+                            baseCurrencyNotionalValue: notionalByInstrument.get(holding.instrumentId) ?? 0,
+                            baseCurrencyMarketValue: valueByInstrument.get(holding.instrumentId) ?? 0,
+                            settlementStyle: holding.settlementStyle,
+                            netAssetValue,
+                            maximumPositionWeight: positionLimit,
+                            accounts: holding.accounts.join(', '),
+                        },
+                    });
+                }
+            }
+            if (groupLimits.length > 0) {
+                const usable = groupLimits.filter((limit) => {
+                    if (limit.group.sleeveId !== undefined && !declaredSleeves.has(limit.group.sleeveId)) {
+                        warnings.push(`${family}: limits.maximumGroupWeights names sleeve '${limit.group.sleeveId}', which policy.model declares no sleeve for — the group cannot be resolved and is not monitored.`);
+                        return false;
+                    }
+                    return true;
+                });
+                // Membership through the ONE resolution law: zero-weight synthetic targets expand to the
+                // same member lists a real target would (sleeve tree, classification, currency).
+                const membership = expandTargets(functionName, expansionInput(usable.map((limit) => ({ group: limit.group, weight: 0 }))));
+                for (const limit of usable) {
+                    const key = targetGroupKey(limit.group);
+                    const group = membership.groupTargets.find((g) => g.key === key);
+                    const members = group?.members ?? [];
+                    const signed = isCashTargetGroup(limit.group)
+                        ? cashWeight
+                        : stableSum(members.map((id) => weightOf(id)));
+                    const absolute = Math.abs(signed);
+                    const bound = rule.threshold ?? limit.maximumWeight;
+                    list.push({
+                        key,
+                        subject: `group ${key}`,
+                        value: absolute,
+                        threshold: bound,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `group ${key} weighs ${pretty(absolute)} of NAV against its maximumWeight ${pretty(bound)}`,
+                        evidence: {
+                            weight: signed,
+                            absoluteWeight: absolute,
+                            maximumWeight: bound,
+                            members: members.length === 0 ? null : members.join(', '),
+                            memberCount: members.length,
+                            netAssetValue,
+                        },
+                    });
+                }
+            }
+            evaluate(family, list);
+        }
+    }
+    // leverage-limit
+    {
+        const family = 'leverage-limit';
+        if (limits.maximumGrossLeverage === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled)
+                skip(family, 'policy declares no limits.maximumGrossLeverage');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (gate(family, true)) {
+            const values = [...notionalByInstrument.values()];
+            const long = stableSum(values.map((v) => Math.max(0, v)));
+            const short = stableSum(values.map((v) => Math.max(0, -v)));
+            const gross = long + short;
+            const nav = netAssetValue;
+            const leverage = gross / nav;
+            const bound = rules[family].threshold;
+            evaluate(family, [
+                {
+                    key: 'portfolio',
+                    subject: 'portfolio',
+                    value: leverage,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `gross notional exposure ${pretty(gross)} ÷ NAV ${pretty(nav)} = ${pretty(leverage)} against maximumGrossLeverage ${pretty(bound)}`,
+                    evidence: {
+                        grossExposure: gross,
+                        longExposure: long,
+                        shortExposure: short,
+                        netExposure: long - short,
+                        exposureBasis: 'baseCurrencyNotionalValue',
+                        netAssetValue: nav,
+                        maximumGrossLeverage: bound,
+                    },
+                },
+            ]);
+        }
+    }
+    // drawdown
+    {
+        const family = 'drawdown';
+        if (limits.maximumDrawdown === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled)
+                skip(family, 'policy declares no limits.maximumDrawdown');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (rules[family].enabled && unvaluedReason !== null) {
+            skip(family, unvaluedReason);
+        }
+        else if (gate(family, false)) {
+            const nav = netAssetValue;
+            const peak = peakNetAssetValue;
+            if (peak <= 0) {
+                skip(family, `peak net asset value ${peak} is not positive; a drawdown from it is undefined`);
+            }
+            else {
+                const drawdown = 1 - nav / peak;
+                const bound = rules[family].threshold;
+                evaluate(family, [
+                    {
+                        key: 'portfolio',
+                        subject: 'portfolio',
+                        value: drawdown,
+                        threshold: bound,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `NAV ${pretty(nav)} is ${pretty(drawdown)} below its peak ${pretty(peak)} against maximumDrawdown ${pretty(bound)}`,
+                        evidence: {
+                            netAssetValue: nav,
+                            peakNetAssetValue: peak,
+                            drawdown,
+                            maximumDrawdown: bound,
+                        },
+                    },
+                ]);
+            }
+        }
+    }
+    // daily-loss
+    {
+        const family = 'daily-loss';
+        if (limits.maximumDailyLoss === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled)
+                skip(family, 'policy declares no limits.maximumDailyLoss');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (rules[family].enabled && unvaluedReason !== null) {
+            skip(family, unvaluedReason);
+        }
+        else if (gate(family, false)) {
+            if (previous === null) {
+                skip(family, 'first evaluation — there is no previous net asset value to measure a loss from');
+            }
+            else if (previous.netAssetValue === null) {
+                skip(family, `the previous evaluation (${epochMsToUtcDate(previous.asOf)}) was unvalued — there is no previous net asset value to measure a loss from`);
+            }
+            else if (previous.netAssetValue <= 0) {
+                skip(family, `the previous net asset value ${previous.netAssetValue} is not positive; a loss fraction of it is undefined`);
+            }
+            else {
+                const nav = netAssetValue;
+                const before = previous.netAssetValue;
+                const loss = (before - nav) / before;
+                const bound = rules[family].threshold;
+                evaluate(family, [
+                    {
+                        key: 'portfolio',
+                        subject: 'portfolio',
+                        value: loss,
+                        threshold: bound,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `NAV moved from ${pretty(before)} (${epochMsToUtcDate(previous.asOf)}) to ${pretty(nav)}, a loss of ${pretty(loss)} against maximumDailyLoss ${pretty(bound)}`,
+                        evidence: {
+                            previousNetAssetValue: before,
+                            previousAsOf: previous.asOf,
+                            netAssetValue: nav,
+                            change: nav - before,
+                            loss,
+                            maximumDailyLoss: bound,
+                        },
+                    },
+                ]);
+            }
+        }
+    }
+    // cash-reserve
+    {
+        const family = 'cash-reserve';
+        const rule = rules[family];
+        if (policy.minimumCash === undefined &&
+            policy.minimumCashWeight === undefined &&
+            !ruleDeclaresThreshold(family)) {
+            if (rule.enabled)
+                skip(family, 'policy declares no minimumCash or minimumCashWeight');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (!rule.enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+        }
+        else {
+            const fromWeight = policy.minimumCashWeight === undefined
+                ? null
+                : netAssetValue === null
+                    ? undefined
+                    : policy.minimumCashWeight * netAssetValue;
+            if (fromWeight === undefined && rule.threshold === null && policy.minimumCash === undefined) {
+                skip(family, `${unvaluedReason ?? 'unvalued'} — minimumCashWeight needs NAV; declare minimumCash to monitor an absolute floor without marks`);
+            }
+            else {
+                if (fromWeight === undefined) {
+                    warnings.push(`${family}: minimumCashWeight cannot be applied while the portfolio is unvalued; only minimumCash is enforced this evaluation.`);
+                }
+                const candidates = [];
+                if (policy.minimumCash !== undefined) {
+                    candidates.push({ floor: policy.minimumCash, source: 'minimumCash' });
+                }
+                if (fromWeight !== null && fromWeight !== undefined) {
+                    candidates.push({ floor: fromWeight, source: 'minimumCashWeight' });
+                }
+                const binding = candidates.length === 0
+                    ? null
+                    : candidates.reduce((best, c) => (c.floor > best.floor ? c : best));
+                const bound = rule.threshold ?? binding?.floor ?? null;
+                rules[family] = {
+                    ...rule,
+                    threshold: bound,
+                    thresholdSource: rule.thresholdSource === 'rule' ? 'rule' : 'policy',
+                };
+                evaluate(family, [
+                    {
+                        key: 'portfolio',
+                        subject: 'portfolio',
+                        value: totalCash,
+                        threshold: bound,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `cash ${pretty(totalCash)} ${baseCurrency} against a reserve floor of ${pretty(bound)} ${baseCurrency}${binding === null ? '' : ` (binding: ${binding.source})`}`,
+                        evidence: {
+                            cash: totalCash,
+                            baseCurrency,
+                            minimumCash: policy.minimumCash ?? null,
+                            minimumCashWeight: policy.minimumCashWeight ?? null,
+                            minimumCashFromWeight: fromWeight ?? null,
+                            netAssetValue,
+                            bindingFloor: rule.threshold !== null ? 'rule' : (binding?.source ?? null),
+                            floor: bound,
+                        },
+                    },
+                ]);
+            }
+        }
+    }
+    // margin-pressure
+    {
+        const family = 'margin-pressure';
+        if (limits.minimumSettledCash === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled)
+                skip(family, 'policy declares no limits.minimumSettledCash');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (gate(family, false)) {
+            let settled = 0;
+            let receivable = 0;
+            let payable = 0;
+            for (const row of cashRows) {
+                const toBase = (amount, subject) => row.currency === baseCurrency
+                    ? amount
+                    : convertWithQuotes({
+                        functionName,
+                        amount,
+                        fromCurrency: row.currency,
+                        toCurrency: baseCurrency,
+                        quotes,
+                        subject,
+                    }).convertedAmount;
+                settled += toBase(row.settledAmount, `account '${row.accountId}' ${row.currency} settled cash`);
+                receivable += toBase(row.unsettledReceivable, `account '${row.accountId}' ${row.currency} receivable`);
+                payable += toBase(row.unsettledPayable, `account '${row.accountId}' ${row.currency} payable`);
+            }
+            const bound = rules[family].threshold;
+            evaluate(family, [
+                {
+                    key: 'portfolio',
+                    subject: 'portfolio',
+                    value: settled,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `settled cash ${pretty(settled)} ${baseCurrency} against minimumSettledCash ${pretty(bound)} ${baseCurrency}`,
+                    evidence: {
+                        settledCash: settled,
+                        totalCash,
+                        unsettledReceivable: receivable,
+                        unsettledPayable: payable,
+                        baseCurrency,
+                        minimumSettledCash: bound,
+                    },
+                },
+            ]);
+        }
+    }
+    // liquidity
+    {
+        const family = 'liquidity';
+        if (limits.maximumDaysToLiquidate === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled)
+                skip(family, 'policy declares no limits.maximumDaysToLiquidate');
+            else
+                skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (gate(family, false)) {
+            if (volumes === undefined) {
+                skip(family, 'no averageDailyVolumes supplied — days to liquidate need a daily volume per instrument');
+            }
+            else {
+                const list = [];
+                const missing = [];
+                const bound = rules[family].threshold;
+                for (const holding of holdings) {
+                    const volume = ownValue(volumes, holding.instrumentId);
+                    if (volume === undefined) {
+                        missing.push(holding.instrumentId);
+                        continue;
+                    }
+                    const quantity = Math.abs(holding.quantity);
+                    const days = quantity / (volume * MONITOR_LIQUIDITY_PARTICIPATION_RATE);
+                    list.push({
+                        key: holding.instrumentId,
+                        subject: `instrument ${holding.instrumentId}`,
+                        value: days,
+                        threshold: bound,
+                        forcedBreach: false,
+                        reason: null,
+                        condition: `${pretty(quantity)} ${holding.instrumentId} at ${pretty(volume)} units/day × ${MONITOR_LIQUIDITY_PARTICIPATION_RATE} participation takes ${pretty(days)} days against maximumDaysToLiquidate ${pretty(bound)}`,
+                        evidence: {
+                            quantity: holding.quantity,
+                            averageDailyVolume: volume,
+                            participationRate: MONITOR_LIQUIDITY_PARTICIPATION_RATE,
+                            daysToLiquidate: days,
+                            maximumDaysToLiquidate: bound,
+                        },
+                    });
+                }
+                if (missing.length > 0) {
+                    warnings.push(`${family}: no averageDailyVolumes entry for ${missing.join(', ')} — days to liquidate ${missing.length === 1 ? 'is' : 'are'} not computable for ${missing.length === 1 ? 'it' : 'them'}.`);
+                }
+                evaluate(family, list);
+            }
+        }
+    }
+    // The option positions (aggregated across accounts) — the two contract-term families below
+    // read the terms the fold carried from the opening fill; neither needs the portfolio valued.
+    const optionHoldings = holdings.flatMap((holding) => holding.contract !== null && holding.contract.kind === 'option'
+        ? [{ holding, contract: holding.contract }]
+        : []);
+    const describeOption = (holding, contract) => `${holding.instrumentId} (${pretty(holding.quantity)} × ${contract.underlyingInstrumentId} ${contract.type} ${pretty(contract.strikePricePerUnit)} expiring ${epochMsToUtcDate(contract.expiryTimestampMs)})`;
+    // option-expiration
+    {
+        const family = 'option-expiration';
+        if (optionExpirationWarningDays === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled) {
+                skip(family, 'no optionExpirationWarningDays supplied — how many days before expiry count as near is a goal, not a default');
+            }
+            else {
+                skip(family, `rules['${family}'].enabled is false`);
+            }
+        }
+        else if (gate(family, false)) {
+            const list = [];
+            const bound = rules[family].threshold;
+            for (const { holding, contract } of optionHoldings) {
+                const daysToExpiry = (contract.expiryTimestampMs - asOf) / MS_PER_DAY;
+                const underlying = usableSpot(spots, contract.underlyingInstrumentId, holding.currency);
+                const when = daysToExpiry < 0
+                    ? `expired ${pretty(-daysToExpiry)} days before asOf with no lifecycle event recorded`
+                    : `expires in ${pretty(daysToExpiry)} days`;
+                list.push({
+                    key: holding.instrumentId,
+                    subject: `instrument ${holding.instrumentId}`,
+                    value: daysToExpiry,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `${describeOption(holding, contract)} ${when} against optionExpirationWarningDays ${pretty(bound)}`,
+                    evidence: {
+                        expiryDate: epochMsToUtcDate(contract.expiryTimestampMs),
+                        expiryTimestampMs: contract.expiryTimestampMs,
+                        daysToExpiry,
+                        quantity: holding.quantity,
+                        contractMultiplier: holding.contractMultiplier,
+                        type: contract.type,
+                        strikePricePerUnit: contract.strikePricePerUnit,
+                        underlyingInstrumentId: contract.underlyingInstrumentId,
+                        underlyingMark: underlying.price,
+                        optionExpirationWarningDays: bound,
+                        accounts: holding.accounts.join(', '),
+                    },
+                });
+            }
+            evaluate(family, list);
+        }
+    }
+    // assignment-risk
+    {
+        const family = 'assignment-risk';
+        if (assignmentRiskMoneyness === undefined && !ruleDeclaresThreshold(family)) {
+            if (rules[family].enabled) {
+                skip(family, 'no assignmentRiskMoneyness supplied — the moneyness at which a short option counts as at risk of assignment is a goal, not a default');
+            }
+            else {
+                skip(family, `rules['${family}'].enabled is false`);
+            }
+        }
+        else if (gate(family, false)) {
+            const list = [];
+            const bound = rules[family].threshold;
+            for (const { holding, contract } of optionHoldings) {
+                if (holding.quantity >= 0)
+                    continue; // only a WRITER can be assigned
+                const daysToExpiry = (contract.expiryTimestampMs - asOf) / MS_PER_DAY;
+                const strike = contract.strikePricePerUnit;
+                const underlying = usableSpot(spots, contract.underlyingInstrumentId, holding.currency);
+                const base = {
+                    key: holding.instrumentId,
+                    subject: `instrument ${holding.instrumentId}`,
+                    threshold: bound,
+                };
+                const evidence = {
+                    underlyingInstrumentId: contract.underlyingInstrumentId,
+                    underlyingMark: underlying.price,
+                    strikePricePerUnit: strike,
+                    type: contract.type,
+                    daysToExpiry,
+                    expiryDate: epochMsToUtcDate(contract.expiryTimestampMs),
+                    quantity: holding.quantity,
+                    contractMultiplier: holding.contractMultiplier,
+                    assignmentRiskMoneyness: bound,
+                    accounts: holding.accounts.join(', '),
+                };
+                if (underlying.price === null) {
+                    // The stale-market-data law: a missing mark is an alert, not a crash, and not a guess.
+                    list.push({
+                        ...base,
+                        value: null,
+                        forcedBreach: true,
+                        reason: underlying.reason,
+                        condition: `short ${describeOption(holding, contract)} cannot be measured for assignment risk — ${underlying.reason}`,
+                        evidence: { ...evidence, moneyness: null, reason: underlying.reason },
+                    });
+                    continue;
+                }
+                if (strike <= 0) {
+                    const reason = `strikePricePerUnit ${strike} is not positive; moneyness as a fraction of the strike is undefined`;
+                    list.push({
+                        ...base,
+                        value: null,
+                        forcedBreach: false,
+                        reason,
+                        condition: `short ${describeOption(holding, contract)} — ${reason}`,
+                        evidence: { ...evidence, moneyness: null, reason },
+                    });
+                    continue;
+                }
+                const moneyness = contract.type === 'call'
+                    ? (underlying.price - strike) / strike
+                    : (strike - underlying.price) / strike;
+                list.push({
+                    ...base,
+                    value: moneyness,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `short ${describeOption(holding, contract)} is ${pretty(Math.abs(moneyness))} ${moneyness >= 0 ? 'in' : 'out of'} the money at ${contract.underlyingInstrumentId} ${pretty(underlying.price)} against assignmentRiskMoneyness ${pretty(bound)}`,
+                    evidence: { ...evidence, moneyness, reason: null },
+                });
+            }
+            evaluate(family, list);
+        }
+    }
+    // stale-market-data
+    {
+        const family = 'stale-market-data';
+        const rule = rules[family];
+        if (!rule.enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (stalenessLimitMs === undefined &&
+            !ruleDeclaresThreshold(family) &&
+            unusable.size === 0) {
+            skip(family, 'no marketStalenessLimitMs supplied and every held instrument has a usable mark — mark age is measured only against a declared limit');
+        }
+        else {
+            const list = [];
+            const bound = rule.threshold;
+            for (const holding of holdings) {
+                const reason = unusable.get(holding.instrumentId);
+                if (reason !== undefined) {
+                    list.push({
+                        key: holding.instrumentId,
+                        subject: `instrument ${holding.instrumentId}`,
+                        value: null,
+                        threshold: bound,
+                        forcedBreach: true,
+                        reason,
+                        condition: `${holding.instrumentId} cannot be marked — ${reason}`,
+                        evidence: {
+                            reason,
+                            markTimestampMs: null,
+                            marketAsOf: market.asOf,
+                            ageMs: null,
+                            marketStalenessLimitMs: bound,
+                            quantity: holding.quantity,
+                        },
+                    });
+                    continue;
+                }
+                if (bound === null && rule.hysteresis === null)
+                    continue;
+                const spot = ownValue(spots, holding.instrumentId);
+                const markTimestampMs = spot.timestampMs ?? market.asOf;
+                const ageMs = asOf - markTimestampMs;
+                list.push({
+                    key: holding.instrumentId,
+                    subject: `instrument ${holding.instrumentId}`,
+                    value: ageMs,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `the ${holding.instrumentId} mark is ${pretty(ageMs)} ms old (observed ${markTimestampMs}) against marketStalenessLimitMs ${pretty(bound)}`,
+                    evidence: {
+                        reason: null,
+                        markTimestampMs,
+                        marketAsOf: market.asOf,
+                        ageMs,
+                        marketStalenessLimitMs: bound,
+                        quantity: holding.quantity,
+                        markSource: spot.timestampMs === undefined ? 'snapshot asOf' : 'spot.timestampMs',
+                    },
+                });
+            }
+            evaluate(family, list);
+        }
+    }
+    // reconciliation-difference
+    {
+        const family = 'reconciliation-difference';
+        if (!rules[family].enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (reconciliation === undefined) {
+            skip(family, 'no reconciliation result supplied — pass reconcilePortfolio’s result to monitor it');
+        }
+        else {
+            const unexplained = reconciliation.differenceCount - reconciliation.explainedCount;
+            const bound = rules[family].threshold;
+            evaluate(family, [
+                {
+                    key: 'portfolio',
+                    subject: 'portfolio',
+                    value: unexplained,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `reconciliation at ${epochMsToUtcDate(reconciliation.asOf)} reports ${reconciliation.differenceCount} difference${reconciliation.differenceCount === 1 ? '' : 's'}, ${reconciliation.explainedCount} explained (${unexplained} unexplained against a tolerance of ${pretty(bound)})`,
+                    evidence: {
+                        reconciled: reconciliation.reconciled ? 'true' : 'false',
+                        differenceCount: reconciliation.differenceCount,
+                        explainedCount: reconciliation.explainedCount,
+                        unexplainedCount: unexplained,
+                        reconciliationAsOf: reconciliation.asOf,
+                        suggestedCorrectionCount: reconciliation.suggestedCorrections.length,
+                    },
+                },
+            ]);
+        }
+    }
+    // unexplained-residual
+    {
+        const family = 'unexplained-residual';
+        if (!rules[family].enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (pnl === undefined) {
+            skip(family, 'no pnl result supplied — pass portfolioPnl’s result to monitor its residual');
+        }
+        else if (residualTolerance === undefined && !ruleDeclaresThreshold(family)) {
+            skip(family, 'no residualTolerance supplied — the tolerated residual is a goal, not a default');
+        }
+        else {
+            const magnitude = Math.abs(pnl.residual);
+            const bound = rules[family].threshold;
+            evaluate(family, [
+                {
+                    key: 'portfolio',
+                    subject: 'portfolio',
+                    value: magnitude,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `the P&L identity over ${pnl.from.valuationDate} → ${pnl.to.valuationDate} leaves ${pretty(pnl.residual)} ${baseCurrency} unexplained against residualTolerance ${pretty(bound)}`,
+                    evidence: {
+                        residual: pnl.residual,
+                        absoluteResidual: magnitude,
+                        investmentReturn: pnl.investmentReturn,
+                        totalPnl: pnl.components.totalPnl,
+                        from: pnl.from.valuationDate,
+                        to: pnl.to.valuationDate,
+                        residualTolerance: bound,
+                    },
+                },
+            ]);
+        }
+    }
+    // unusual-pnl
+    {
+        const family = 'unusual-pnl';
+        if (!rules[family].enabled) {
+            skip(family, `rules['${family}'].enabled is false`);
+        }
+        else if (pnl === undefined) {
+            skip(family, 'no pnl result supplied — pass portfolioPnl’s result to monitor its size');
+        }
+        else if (unusualPnlThreshold === undefined && !ruleDeclaresThreshold(family)) {
+            skip(family, 'no unusualPnlThreshold supplied — what counts as unusual is a goal, not a default');
+        }
+        else if (gate(family, true)) {
+            const nav = netAssetValue;
+            const ratio = Math.abs(pnl.components.totalPnl) / nav;
+            const bound = rules[family].threshold;
+            evaluate(family, [
+                {
+                    key: 'portfolio',
+                    subject: 'portfolio',
+                    value: ratio,
+                    threshold: bound,
+                    forcedBreach: false,
+                    reason: null,
+                    condition: `P&L of ${pretty(pnl.components.totalPnl)} ${baseCurrency} over ${pnl.from.valuationDate} → ${pnl.to.valuationDate} is ${pretty(ratio)} of NAV ${pretty(nav)} against unusualPnlThreshold ${pretty(bound)}`,
+                    evidence: {
+                        totalPnl: pnl.components.totalPnl,
+                        investmentReturn: pnl.investmentReturn,
+                        residual: pnl.residual,
+                        netAssetValue: nav,
+                        ratioOfNetAssetValue: ratio,
+                        from: pnl.from.valuationDate,
+                        to: pnl.to.valuationDate,
+                        unusualPnlThreshold: bound,
+                    },
+                },
+            ]);
+        }
+    }
+    // ---- the state machine over every observation; vanished and carried rules ----
+    const priorRules = previous?.rules ?? {};
+    const acknowledgedNow = new Set(acknowledgments);
+    for (const key of acknowledgments) {
+        if (ownValue(priorRules, key)?.active !== true) {
+            warnings.push(`acknowledgments names '${key}', which is not an active rule in previousState — ignored (an acknowledgment attaches to an active alert).`);
+        }
+    }
+    const nextRules = {};
+    const alerts = [];
+    const observedKeys = new Set();
+    for (const [family, list] of observations) {
+        const rule = rules[family];
+        for (const observation of list) {
+            const key = `${family}:${observation.key}`;
+            observedKeys.add(key);
+            const prior = ownValue(priorRules, key);
+            const result = transition(prior, rule, observation, asOf, acknowledgedNow.has(key));
+            if (!result.computable) {
+                warnings.push(`${family}: ${observation.subject} is not computable this evaluation${observation.reason === null ? '' : ` — ${observation.reason}`}; its prior state is carried forward.`);
+                if (result.next !== null)
+                    setOwnValue(nextRules, key, result.next);
+                continue;
+            }
+            if (result.next !== null)
+                setOwnValue(nextRules, key, result.next);
+            if (result.alertState === null)
+                continue;
+            alerts.push({
+                key,
+                family,
+                subject: observation.subject,
+                severity: rule.severity,
+                state: result.alertState,
+                value: observation.value,
+                threshold: result.bound,
+                direction: rule.direction,
+                message: `${family} ${result.alertState}: ${observation.condition}.`,
+                evidence: {
+                    ...observation.evidence,
+                    ...(rule.hysteresis !== null
+                        ? { enterThreshold: rule.hysteresis.enter, exitThreshold: rule.hysteresis.exit }
+                        : {}),
+                    consecutiveBreaches: result.next?.consecutiveBreaches ?? 0,
+                    lastRaisedAtMs: result.next?.lastRaisedAtMs ?? null,
+                },
+            });
+        }
+    }
+    const carriedActive = [];
+    for (const key of Object.keys(priorRules).sort(compareKeys)) {
+        if (observedKeys.has(key))
+            continue;
+        const family = familyOfKey(key);
+        const prior = ownValue(priorRules, key);
+        if (!observations.has(family)) {
+            // The family was skipped: unknown is not cleared — carry the entry forward verbatim.
+            setOwnValue(nextRules, key, { ...prior });
+            if (prior.active)
+                carriedActive.push(key);
+            continue;
+        }
+        if (!prior.active)
+            continue;
+        // The family evaluated and the subject is gone (a closed position, a removed target): clear.
+        const rule = rules[family];
+        const subject = key.slice(family.length + 1);
+        alerts.push({
+            key,
+            family,
+            subject,
+            severity: rule.severity,
+            state: 'cleared',
+            value: null,
+            threshold: rule.threshold,
+            direction: rule.direction,
+            message: `${family} cleared: ${subject} is no longer observed (the position closed or the target was removed).`,
+            evidence: {
+                reason: 'subject no longer observed',
+                lastValue: prior.lastValue,
+                lastRaisedAtMs: prior.lastRaisedAtMs,
+                consecutiveBreaches: 0,
+            },
+        });
+    }
+    if (carriedActive.length > 0) {
+        warnings.push(`${carriedActive.length} active rule${carriedActive.length === 1 ? '' : 's'} in skipped families carried forward unevaluated: ${carriedActive.join(', ')}.`);
+    }
+    alerts.sort((a, b) => compareKeys(a.key, b.key));
+    const sortedRules = {};
+    for (const key of Object.keys(nextRules).sort(compareKeys)) {
+        setOwnValue(sortedRules, key, ownValue(nextRules, key));
+    }
+    const nextState = {
+        schemaVersion: PORTFOLIO_MONITOR_STATE_SCHEMA_VERSION,
+        asOf,
+        netAssetValue,
+        peakNetAssetValue,
+        evaluationCount: (previous?.evaluationCount ?? 0) + 1,
+        rules: sortedRules,
+    };
+    const count = (alertState) => alerts.filter((alert) => alert.state === alertState).length;
+    return deepFreeze(requireRepresentableResult(functionName, {
+        asOf,
+        baseCurrency,
+        netAssetValue,
+        alerts,
+        evaluated: evaluations,
+        state: nextState,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            liquidityParticipationRate: MONITOR_LIQUIDITY_PARTICIPATION_RATE,
+            conventions: CONVENTIONS,
+            rulesApplied: rules,
+        },
+        diagnostics: {
+            warnings,
+            unsupportedFamilies: DEFERRED_FAMILIES.map((entry) => ({ ...entry })),
+            raisedCount: count('raised'),
+            activeCount: Object.values(sortedRules).filter((entry) => entry.active).length,
+            clearedCount: count('cleared'),
+            suppressedCount: count('suppressed'),
+            acknowledgedCount: count('acknowledged'),
+        },
+    }));
+}
+//# sourceMappingURL=monitor.js.map