@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/policy-grammar.js

@@ -0,0 +1,1198 @@
+/**
+ * The investment-policy grammar behind `@insiderfinance/totalfinance/portfolio/policy` (FC7 slice 4, Stage 4.4): model
+ * portfolios with versioned strategic/tactical/glide-path targets and hierarchical sleeves, the
+ * user-supplied `InvestmentPolicy`, and the ONE target-resolution law that `allocatePortfolio`,
+ * `proposePortfolioRebalance`, and `monitorPortfolio` share. This module is INTERNAL: `policy.ts`
+ * is the public subpath and re-exports only the reviewed surface.
+ *
+ * Decisions this module executes (agent-native doc, "Portfolio management workflows" →
+ * "Investment policy"; tracker §FC7 "Portfolio-side management"):
+ *
+ * - A policy is a USER-SUPPLIED artifact, never advice: every goal is explicit and **missing goals
+ *   do not become secret defaults** — a group target with no way to split it, a universe the
+ *   targets do not cover, or a risk budget without a covariance is reported as `unresolved`, never
+ *   quietly filled in.
+ * - Targets are declared on GROUPS (`instrumentId`, `sleeveId`, `assetClass`, `currency`, `tag`,
+ *   `underlying`, `strategy`) — the same identity vocabulary the P&L and timeline groupings use —
+ *   and `{ assetClass: 'cash' }` is THE cash target (the accepted example's spelling).
+ * - A model portfolio is an immutable, content-addressed artifact (`kind: 'totalfinance.model-portfolio'`)
+ *   whose targets resolve at an explicit `asOf`: tactical sets effective at that instant win over
+ *   the glide path, which wins over the strategic set. Nothing is interpolated unless the model says
+ *   `interpolation: 'linear'`.
+ */
+import { CONVENTIONS_VERSION, DataError, ErrorCode, InputError, ensureKnownKeys, requireArgumentArray, requireArgumentObject, resolveAsOf, } from '../../core/dist/index.js';
+import { contentHash } from '../../core/dist/artifacts/index.js';
+import { deepFreeze, describeInputValue, epochMsToUtcDate, ownValue, requireCurrencyCode, requireEpochMsField, requireFiniteNumberField, requireIdentityString, requirePositiveNumberField, } from './internal.js';
+export const MODEL_PORTFOLIO_KIND = 'totalfinance.model-portfolio';
+export const MODEL_PORTFOLIO_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------------------------------
+const TARGET_GROUP_KEYS = [
+    'instrumentId',
+    'sleeveId',
+    'assetClass',
+    'currency',
+    'tag',
+    'underlying',
+    'strategy',
+];
+const TARGET_KEYS = ['group', 'weight', 'riskBudget', 'driftBand'];
+const TARGET_SET_KEYS = ['effectiveFrom', 'effectiveTo', 'targets', 'note'];
+const SLEEVE_KEYS = [
+    'sleeveId',
+    'parentSleeveId',
+    'weightWithinParent',
+    'members',
+    'note',
+];
+const SLEEVE_MEMBER_KEYS = ['instrumentId', 'weight'];
+const BENCHMARK_KEYS = ['benchmarkId', 'asOf', 'constituents'];
+const CONSTITUENT_KEYS = ['instrumentId', 'weight'];
+const LIABILITY_KEYS = ['entries', 'note'];
+const LIABILITY_ENTRY_KEYS = ['date', 'amount', 'currency'];
+const GLIDE_PATH_KEYS = ['interpolation', 'points'];
+const GLIDE_INTERPOLATIONS = ['step', 'linear'];
+const DEFINITION_KEYS = [
+    'modelId',
+    'version',
+    'baseCurrency',
+    'strategic',
+    'tactical',
+    'glidePath',
+    'sleeves',
+    'benchmark',
+    'liabilities',
+    'horizonEndDate',
+    'note',
+];
+const ARTIFACT_KEYS = [...DEFINITION_KEYS, 'kind', 'schemaVersion', 'contentHash'];
+const LIMIT_KEYS = [
+    'maximumPositionWeight',
+    'maximumGroupWeights',
+    'maximumGrossLeverage',
+    'maximumDrawdown',
+    'maximumDailyLoss',
+    'maximumDaysToLiquidate',
+    'minimumSettledCash',
+];
+const GROUP_LIMIT_KEYS = ['group', 'maximumWeight'];
+const POLICY_KEYS = [
+    'targets',
+    'model',
+    'withinGroupAllocation',
+    'driftBand',
+    'reviewCadenceDays',
+    'maximumTurnover',
+    'maximumEstimatedTransactionCost',
+    'minimumCash',
+    'minimumCashWeight',
+    'limits',
+    'allowedInstruments',
+    'restrictedInstruments',
+    'allowedAccounts',
+    'benchmark',
+    'performanceObjective',
+    'contributionHandling',
+    'withdrawalHandling',
+    'incomeReinvestment',
+    'lotSelectionObjective',
+];
+const WITHIN_GROUP_ALLOCATIONS = [
+    'proportional-to-current',
+    'equal',
+];
+const CONTRIBUTION_HANDLINGS = [
+    'invest-to-targets',
+    'hold-as-cash',
+];
+const WITHDRAWAL_HANDLINGS = ['raise-from-overweights', 'pro-rata'];
+const INCOME_REINVESTMENTS = ['reinvest', 'hold-as-cash'];
+/** Weight sums are compared at this tolerance (float arithmetic on declared decimals). */
+export const WEIGHT_TOLERANCE = 1e-9;
+/** The cash target's spelling — the accepted example's `{ assetClass: 'cash' }`. */
+export const CASH_ASSET_CLASS = 'cash';
+const MODEL_EXAMPLE_CALL = "createModelPortfolio({ modelId: 'balanced', version: 1, baseCurrency: 'USD', strategic: { effectiveFrom: '2026-01-01', targets: [{ group: { tag: 'equity' }, weight: 0.6 }, { group: { tag: 'fixed-income' }, weight: 0.3 }, { group: { assetClass: 'cash' }, weight: 0.1 }] } })";
+const POLICY_EXAMPLE = "policy: { targets: [{ group: { tag: 'equity' }, weight: 0.6 }, { group: { tag: 'fixed-income' }, weight: 0.3 }, { group: { assetClass: 'cash' }, weight: 0.1 }], withinGroupAllocation: 'proportional-to-current', driftBand: 0.03, maximumTurnover: 0.15, minimumCash: 5_000 }";
+// ---------------------------------------------------------------------------------------------------
+// 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 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 ${describeInputValue(value)}.`, {
+            code: typeof value === 'string' ? ErrorCode.InputInvalidEnum : ErrorCode.InputWrongType,
+            context: { function: functionName, field },
+        });
+    }
+    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 requireInstant(functionName, field, value) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new InputError(`${functionName}: ${field} must be an epoch-millisecond number, a 'YYYY-MM-DD' date, or a zoned ISO datetime. Received ${value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field } });
+    }
+    const resolved = resolveAsOf(value, functionName);
+    requireEpochMsField(functionName, field, resolved);
+    return resolved;
+}
+function requireIdentityList(functionName, field, value) {
+    requireArgumentArray(functionName, field, value);
+    const out = [];
+    const seen = new Set();
+    value.forEach((entry, index) => {
+        requireIdentityString(functionName, `${field}[${index}]`, entry);
+        if (seen.has(entry)) {
+            outOfRange(functionName, field, `${field} lists '${entry}' twice.`);
+        }
+        seen.add(entry);
+        out.push(entry);
+    });
+    return out;
+}
+/** A declared-weight total for prose: 12 significant digits, so 0.6 + 0.3 reads 0.9. */
+function readable(value) {
+    return String(Number(value.toPrecision(12)));
+}
+function sum(values) {
+    let total = 0;
+    for (const value of values)
+        total += value;
+    return total;
+}
+/** The single key of a validated target group, as `'<dimension>:<value>'`. */
+export function targetGroupKey(group) {
+    for (const key of TARGET_GROUP_KEYS) {
+        const value = group[key];
+        if (value !== undefined)
+            return `${key}:${value}`;
+    }
+    throw new DataError('targetGroupKey: the group names no dimension.', {
+        code: ErrorCode.InputMissingField,
+        context: { function: 'targetGroupKey', field: 'group' },
+    });
+}
+/** Whether a group is the cash target. */
+export function isCashTargetGroup(group) {
+    return group.assetClass === CASH_ASSET_CLASS;
+}
+// ---------------------------------------------------------------------------------------------------
+// Validation — targets
+// ---------------------------------------------------------------------------------------------------
+/** Validate one target group: an object with exactly ONE dimension key holding an identity string. */
+export function requireTargetGroup(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, TARGET_GROUP_KEYS);
+    const group = value;
+    const present = TARGET_GROUP_KEYS.filter((key) => group[key] !== undefined);
+    if (present.length !== 1) {
+        throw new InputError(`${functionName}: ${path} must name exactly ONE dimension (${TARGET_GROUP_KEYS.join(', ')}); received ${present.length === 0 ? 'none' : present.join(' + ')}. A target on two dimensions is two targets.`, {
+            code: present.length === 0 ? ErrorCode.InputMissingField : ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: path },
+        });
+    }
+    const key = present[0];
+    requireIdentityString(functionName, `${path}.${key}`, group[key]);
+    return { [key]: group[key] };
+}
+/** Validate one allocation target. */
+export function requireAllocationTarget(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, TARGET_KEYS);
+    const target = value;
+    const group = requireTargetGroup(functionName, `${path}.group`, target['group']);
+    const hasWeight = target['weight'] !== undefined;
+    const hasRiskBudget = target['riskBudget'] !== undefined;
+    if (hasWeight === hasRiskBudget) {
+        throw new InputError(`${functionName}: ${path} must declare exactly one of weight (share of NAV) or riskBudget (share of risk)${hasWeight ? ' — both were given' : ' — neither was given'}.\n  e.g. { group: { tag: 'equity' }, weight: 0.6 }`, {
+            code: hasWeight ? ErrorCode.InputOutOfRange : ErrorCode.InputMissingField,
+            context: { function: functionName, field: path },
+        });
+    }
+    const out = { group };
+    if (hasWeight) {
+        requireFiniteNumberField(functionName, `${path}.weight`, target['weight']);
+        if (Math.abs(target['weight']) > 1) {
+            outOfRange(functionName, `${path}.weight`, `${path}.weight is a decimal fraction of NAV, so |weight| ≤ 1. Received ${target['weight']} (a percentage?).`);
+        }
+        out.weight = target['weight'];
+    }
+    else {
+        requireFiniteNumberField(functionName, `${path}.riskBudget`, target['riskBudget']);
+        if (target['riskBudget'] < 0 || target['riskBudget'] > 1) {
+            outOfRange(functionName, `${path}.riskBudget`, `${path}.riskBudget is a decimal share of total risk in [0, 1]. Received ${target['riskBudget']}.`);
+        }
+        out.riskBudget = target['riskBudget'];
+    }
+    if (target['driftBand'] !== undefined) {
+        out.driftBand = requireNonNegative(functionName, `${path}.driftBand`, target['driftBand']);
+    }
+    return out;
+}
+/** Validate a target list: each target valid, no duplicate groups, per-dimension sums ≤ 1. */
+export function requireAllocationTargets(functionName, path, value) {
+    requireArgumentArray(functionName, path, value);
+    if (value.length === 0) {
+        missingField(functionName, path, `${path} must contain at least one target.\n  e.g. ${POLICY_EXAMPLE}`);
+    }
+    const targets = value.map((entry, index) => requireAllocationTarget(functionName, `${path}[${index}]`, entry));
+    const seen = new Set();
+    const weightByDimension = new Map();
+    const riskByDimension = new Map();
+    targets.forEach((target, index) => {
+        const key = targetGroupKey(target.group);
+        if (seen.has(key)) {
+            outOfRange(functionName, `${path}[${index}].group`, `${path} names the group '${key}' twice — one target per group.`);
+        }
+        seen.add(key);
+        const dimension = key.slice(0, key.indexOf(':'));
+        if (target.weight !== undefined) {
+            weightByDimension.set(dimension, (weightByDimension.get(dimension) ?? 0) + target.weight);
+        }
+        else {
+            riskByDimension.set(dimension, (riskByDimension.get(dimension) ?? 0) + target.riskBudget);
+        }
+    });
+    for (const [dimension, total] of weightByDimension) {
+        if (total > 1 + WEIGHT_TOLERANCE) {
+            outOfRange(functionName, path, `${path} allocates ${total} of NAV across the '${dimension}' dimension — weights on one dimension cannot exceed 1.`);
+        }
+    }
+    for (const [dimension, total] of riskByDimension) {
+        if (total > 1 + WEIGHT_TOLERANCE) {
+            outOfRange(functionName, path, `${path} budgets ${total} of total risk across the '${dimension}' dimension — risk budgets on one dimension cannot exceed 1.`);
+        }
+    }
+    return targets;
+}
+function requireTargetSet(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, TARGET_SET_KEYS);
+    const set = value;
+    if (set['effectiveFrom'] === undefined) {
+        missingField(functionName, `${path}.effectiveFrom`, `${path}.effectiveFrom is required — a target set is dated.`);
+    }
+    const effectiveFrom = requireInstant(functionName, `${path}.effectiveFrom`, set['effectiveFrom']);
+    const out = {
+        effectiveFrom: set['effectiveFrom'],
+        targets: requireAllocationTargets(functionName, `${path}.targets`, set['targets']),
+    };
+    if (set['effectiveTo'] !== undefined) {
+        const effectiveTo = requireInstant(functionName, `${path}.effectiveTo`, set['effectiveTo']);
+        if (effectiveTo <= effectiveFrom) {
+            outOfRange(functionName, `${path}.effectiveTo`, `${path}.effectiveTo (${epochMsToUtcDate(effectiveTo)}) must be after effectiveFrom (${epochMsToUtcDate(effectiveFrom)}).`);
+        }
+        out.effectiveTo = set['effectiveTo'];
+    }
+    if (set['note'] !== undefined) {
+        if (typeof set['note'] !== 'string') {
+            throw new InputError(`${functionName}: ${path}.note must be a string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${path}.note` },
+            });
+        }
+        out.note = set['note'];
+    }
+    return out;
+}
+function requireSleeves(functionName, path, value) {
+    requireArgumentArray(functionName, path, value);
+    const sleeves = [];
+    const byId = new Map();
+    value.forEach((entry, index) => {
+        const entryPath = `${path}[${index}]`;
+        requireArgumentObject(functionName, entryPath, entry);
+        ensureKnownKeys(functionName, entryPath, entry, SLEEVE_KEYS);
+        const raw = entry;
+        requireIdentityString(functionName, `${entryPath}.sleeveId`, raw['sleeveId']);
+        if (byId.has(raw['sleeveId'])) {
+            outOfRange(functionName, `${entryPath}.sleeveId`, `${path} declares sleeve '${raw['sleeveId']}' twice.`);
+        }
+        const sleeve = { sleeveId: raw['sleeveId'] };
+        if (raw['parentSleeveId'] !== undefined) {
+            requireIdentityString(functionName, `${entryPath}.parentSleeveId`, raw['parentSleeveId']);
+            if (raw['parentSleeveId'] === sleeve.sleeveId) {
+                outOfRange(functionName, `${entryPath}.parentSleeveId`, `sleeve '${sleeve.sleeveId}' cannot be its own parent.`);
+            }
+            sleeve.parentSleeveId = raw['parentSleeveId'];
+            if (raw['weightWithinParent'] === undefined) {
+                missingField(functionName, `${entryPath}.weightWithinParent`, `${entryPath}.weightWithinParent is required for a child sleeve (siblings sum to 1).`);
+            }
+            sleeve.weightWithinParent = requireNonNegative(functionName, `${entryPath}.weightWithinParent`, raw['weightWithinParent']);
+        }
+        else if (raw['weightWithinParent'] !== undefined) {
+            outOfRange(functionName, `${entryPath}.weightWithinParent`, `${entryPath}.weightWithinParent is only meaningful with parentSleeveId.`);
+        }
+        if (raw['members'] !== undefined) {
+            requireArgumentArray(functionName, `${entryPath}.members`, raw['members']);
+            if (raw['members'].length === 0) {
+                missingField(functionName, `${entryPath}.members`, `${entryPath}.members must not be empty.`);
+            }
+            const seen = new Set();
+            sleeve.members = raw['members'].map((member, memberIndex) => {
+                const memberPath = `${entryPath}.members[${memberIndex}]`;
+                requireArgumentObject(functionName, memberPath, member);
+                ensureKnownKeys(functionName, memberPath, member, SLEEVE_MEMBER_KEYS);
+                const m = member;
+                requireIdentityString(functionName, `${memberPath}.instrumentId`, m['instrumentId']);
+                if (seen.has(m['instrumentId'])) {
+                    outOfRange(functionName, memberPath, `sleeve '${sleeve.sleeveId}' lists '${m['instrumentId']}' twice.`);
+                }
+                seen.add(m['instrumentId']);
+                return {
+                    instrumentId: m['instrumentId'],
+                    weight: requireNonNegative(functionName, `${memberPath}.weight`, m['weight']),
+                };
+            });
+            const total = sum(sleeve.members.map((member) => member.weight));
+            if (Math.abs(total - 1) > WEIGHT_TOLERANCE) {
+                outOfRange(functionName, `${entryPath}.members`, `sleeve '${sleeve.sleeveId}' member weights sum to ${total}; they must sum to 1 (weights are WITHIN the sleeve).`);
+            }
+        }
+        if (raw['note'] !== undefined) {
+            if (typeof raw['note'] !== 'string') {
+                throw new InputError(`${functionName}: ${entryPath}.note must be a string.`, {
+                    code: ErrorCode.InputWrongType,
+                    context: { function: functionName, field: `${entryPath}.note` },
+                });
+            }
+            sleeve.note = raw['note'];
+        }
+        byId.set(sleeve.sleeveId, sleeve);
+        sleeves.push(sleeve);
+    });
+    // Structure: parents exist, no cycles, siblings sum to 1, every sleeve is a leaf or a parent.
+    const children = new Map();
+    for (const sleeve of sleeves) {
+        if (sleeve.parentSleeveId !== undefined) {
+            if (!byId.has(sleeve.parentSleeveId)) {
+                outOfRange(functionName, path, `sleeve '${sleeve.sleeveId}' names parent '${sleeve.parentSleeveId}', which is not declared.`);
+            }
+            const list = children.get(sleeve.parentSleeveId) ?? [];
+            list.push(sleeve);
+            children.set(sleeve.parentSleeveId, list);
+        }
+    }
+    for (const sleeve of sleeves) {
+        const seen = new Set([sleeve.sleeveId]);
+        let cursor = sleeve.parentSleeveId;
+        while (cursor !== undefined) {
+            if (seen.has(cursor)) {
+                outOfRange(functionName, path, `sleeves form a cycle through '${cursor}'.`);
+            }
+            seen.add(cursor);
+            cursor = byId.get(cursor).parentSleeveId;
+        }
+        const kids = children.get(sleeve.sleeveId) ?? [];
+        if (kids.length > 0 && sleeve.members !== undefined) {
+            outOfRange(functionName, path, `sleeve '${sleeve.sleeveId}' declares members AND has child sleeves — a sleeve is a leaf or a parent, not both.`);
+        }
+        if (kids.length === 0 && sleeve.members === undefined) {
+            missingField(functionName, path, `sleeve '${sleeve.sleeveId}' has neither members nor child sleeves — an empty sleeve cannot be allocated.`);
+        }
+        if (kids.length > 0) {
+            const total = sum(kids.map((kid) => kid.weightWithinParent));
+            if (Math.abs(total - 1) > WEIGHT_TOLERANCE) {
+                outOfRange(functionName, path, `the child sleeves of '${sleeve.sleeveId}' weigh ${total} within it; siblings must sum to 1.`);
+            }
+        }
+    }
+    return sleeves;
+}
+function requireBenchmark(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, BENCHMARK_KEYS);
+    const raw = value;
+    requireIdentityString(functionName, `${path}.benchmarkId`, raw['benchmarkId']);
+    const out = { benchmarkId: raw['benchmarkId'] };
+    if (raw['asOf'] !== undefined) {
+        requireInstant(functionName, `${path}.asOf`, raw['asOf']);
+        out.asOf = raw['asOf'];
+    }
+    if (raw['constituents'] !== undefined) {
+        requireArgumentArray(functionName, `${path}.constituents`, raw['constituents']);
+        const seen = new Set();
+        out.constituents = raw['constituents'].map((entry, index) => {
+            const entryPath = `${path}.constituents[${index}]`;
+            requireArgumentObject(functionName, entryPath, entry);
+            ensureKnownKeys(functionName, entryPath, entry, CONSTITUENT_KEYS);
+            const c = entry;
+            requireIdentityString(functionName, `${entryPath}.instrumentId`, c['instrumentId']);
+            if (seen.has(c['instrumentId'])) {
+                outOfRange(functionName, entryPath, `${path} lists '${c['instrumentId']}' twice.`);
+            }
+            seen.add(c['instrumentId']);
+            requireFiniteNumberField(functionName, `${entryPath}.weight`, c['weight']);
+            return { instrumentId: c['instrumentId'], weight: c['weight'] };
+        });
+        if (out.constituents.length === 0) {
+            missingField(functionName, `${path}.constituents`, `${path}.constituents must not be empty when given.`);
+        }
+        const total = sum(out.constituents.map((c) => c.weight));
+        if (Math.abs(total - 1) > WEIGHT_TOLERANCE) {
+            outOfRange(functionName, `${path}.constituents`, `${path}.constituents weigh ${total}; a benchmark's membership sums to 1.`);
+        }
+    }
+    return out;
+}
+function requireLiabilities(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, LIABILITY_KEYS);
+    const raw = value;
+    requireArgumentArray(functionName, `${path}.entries`, raw['entries']);
+    let previous = -Infinity;
+    const entries = raw['entries'].map((entry, index) => {
+        const entryPath = `${path}.entries[${index}]`;
+        requireArgumentObject(functionName, entryPath, entry);
+        ensureKnownKeys(functionName, entryPath, entry, LIABILITY_ENTRY_KEYS);
+        const e = entry;
+        const date = requireInstant(functionName, `${entryPath}.date`, e['date']);
+        if (date < previous) {
+            outOfRange(functionName, `${entryPath}.date`, `${path}.entries must be in non-decreasing date order.`);
+        }
+        previous = date;
+        requirePositiveNumberField(functionName, `${entryPath}.amount`, e['amount'], 'a liability is an amount due');
+        return {
+            date: e['date'],
+            amount: e['amount'],
+            currency: (() => {
+                requireCurrencyCode(functionName, `${entryPath}.currency`, e['currency']);
+                return e['currency'];
+            })(),
+        };
+    });
+    const out = { entries };
+    if (raw['note'] !== undefined) {
+        if (typeof raw['note'] !== 'string') {
+            throw new InputError(`${functionName}: ${path}.note must be a string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${path}.note` },
+            });
+        }
+        out.note = raw['note'];
+    }
+    return out;
+}
+function requireGlidePath(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, GLIDE_PATH_KEYS);
+    const raw = value;
+    if (raw['interpolation'] === undefined) {
+        missingField(functionName, `${path}.interpolation`, `${path}.interpolation is required ('step' holds each point until the next; 'linear' interpolates weights between points) — a glide path's shape is a goal, not a default.`);
+    }
+    const interpolation = requireLiteral(functionName, `${path}.interpolation`, raw['interpolation'], GLIDE_INTERPOLATIONS);
+    requireArgumentArray(functionName, `${path}.points`, raw['points']);
+    if (raw['points'].length === 0) {
+        missingField(functionName, `${path}.points`, `${path}.points must contain at least one dated target set.`);
+    }
+    const points = raw['points'].map((entry, index) => requireTargetSet(functionName, `${path}.points[${index}]`, entry));
+    let previous = -Infinity;
+    points.forEach((point, index) => {
+        const from = resolveAsOf(point.effectiveFrom, functionName);
+        if (from <= previous) {
+            outOfRange(functionName, `${path}.points[${index}].effectiveFrom`, `${path}.points must be in strictly increasing effectiveFrom order.`);
+        }
+        previous = from;
+        if (point.effectiveTo !== undefined) {
+            outOfRange(functionName, `${path}.points[${index}].effectiveTo`, `a glide-path point runs until the next point; effectiveTo is not allowed here.`);
+        }
+        if (interpolation === 'linear' && index > 0) {
+            const before = new Set(points[index - 1].targets.map((t) => targetGroupKey(t.group)));
+            const now = new Set(point.targets.map((t) => targetGroupKey(t.group)));
+            const same = before.size === now.size && [...before].every((k) => now.has(k));
+            if (!same) {
+                outOfRange(functionName, `${path}.points[${index}].targets`, `linear interpolation needs every point to name the SAME groups (point ${index - 1} names ${[...before].join(', ')}; point ${index} names ${[...now].join(', ')}). Use 'step', or restate both points over one group set.`);
+            }
+            const riskMixed = points[index - 1].targets.some((t) => t.riskBudget !== undefined) ||
+                point.targets.some((t) => t.riskBudget !== undefined);
+            if (riskMixed) {
+                outOfRange(functionName, `${path}.points[${index}].targets`, `linear interpolation is defined over weights; risk-budget targets need 'step'.`);
+            }
+        }
+    });
+    return { interpolation, points };
+}
+// ---------------------------------------------------------------------------------------------------
+// Validation — the model and the policy
+// ---------------------------------------------------------------------------------------------------
+/** Validate a {@link ModelPortfolioDefinition} (closed keys, dated sets, sleeve structure). */
+export function requireModelPortfolioDefinition(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, DEFINITION_KEYS);
+    const raw = value;
+    requireIdentityString(functionName, `${path}.modelId`, raw['modelId']);
+    if (raw['version'] === undefined) {
+        missingField(functionName, `${path}.version`, `${path}.version is required (a safe integer ≥ 1; a changed model is a new version).\n  e.g. ${MODEL_EXAMPLE_CALL}`);
+    }
+    const version = requireSafeIntegerAtLeast(functionName, `${path}.version`, raw['version'], 1);
+    requireCurrencyCode(functionName, `${path}.baseCurrency`, raw['baseCurrency']);
+    const baseCurrency = raw['baseCurrency'];
+    if (raw['strategic'] === undefined) {
+        missingField(functionName, `${path}.strategic`, `${path}.strategic is required — the dated strategic target set.\n  e.g. ${MODEL_EXAMPLE_CALL}`);
+    }
+    const out = {
+        modelId: raw['modelId'],
+        version,
+        baseCurrency,
+        strategic: requireTargetSet(functionName, `${path}.strategic`, raw['strategic']),
+    };
+    if (raw['tactical'] !== undefined) {
+        requireArgumentArray(functionName, `${path}.tactical`, raw['tactical']);
+        out.tactical = raw['tactical'].map((entry, index) => requireTargetSet(functionName, `${path}.tactical[${index}]`, entry));
+    }
+    if (raw['glidePath'] !== undefined) {
+        out.glidePath = requireGlidePath(functionName, `${path}.glidePath`, raw['glidePath']);
+    }
+    if (raw['sleeves'] !== undefined) {
+        out.sleeves = requireSleeves(functionName, `${path}.sleeves`, raw['sleeves']);
+    }
+    if (raw['benchmark'] !== undefined) {
+        out.benchmark = requireBenchmark(functionName, `${path}.benchmark`, raw['benchmark']);
+    }
+    if (raw['liabilities'] !== undefined) {
+        out.liabilities = requireLiabilities(functionName, `${path}.liabilities`, raw['liabilities']);
+    }
+    if (raw['horizonEndDate'] !== undefined) {
+        requireInstant(functionName, `${path}.horizonEndDate`, raw['horizonEndDate']);
+        out.horizonEndDate = raw['horizonEndDate'];
+    }
+    if (raw['note'] !== undefined) {
+        if (typeof raw['note'] !== 'string') {
+            throw new InputError(`${functionName}: ${path}.note must be a string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${path}.note` },
+            });
+        }
+        out.note = raw['note'];
+    }
+    // Every sleeve target must name a declared sleeve.
+    const sleeveIds = new Set((out.sleeves ?? []).map((s) => s.sleeveId));
+    const sets = [
+        [`${path}.strategic`, out.strategic],
+        ...(out.tactical ?? []).map((set, i) => [`${path}.tactical[${i}]`, set]),
+        ...(out.glidePath?.points ?? []).map((set, i) => [
+            `${path}.glidePath.points[${i}]`,
+            set,
+        ]),
+    ];
+    for (const [setPath, set] of sets) {
+        set.targets.forEach((target, index) => {
+            if (target.group.sleeveId !== undefined && !sleeveIds.has(target.group.sleeveId)) {
+                outOfRange(functionName, `${setPath}.targets[${index}].group.sleeveId`, `${setPath}.targets[${index}] targets sleeve '${target.group.sleeveId}', which ${path}.sleeves does not declare.`);
+            }
+        });
+    }
+    return out;
+}
+function modelContentHash(definition) {
+    return contentHash({
+        kind: MODEL_PORTFOLIO_KIND,
+        schemaVersion: MODEL_PORTFOLIO_SCHEMA_VERSION,
+        ...definition,
+    });
+}
+/**
+ * Freeze a {@link ModelPortfolioDefinition} into an immutable, content-addressed
+ * {@link ModelPortfolio} artifact. The definition is fully validated first; the hash covers
+ * everything (a changed target is a different model).
+ *
+ * @example
+ * ```ts
+ * import { createModelPortfolio } from '@insiderfinance/totalfinance/portfolio/policy';
+ *
+ * const model = createModelPortfolio({
+ *   modelId: 'balanced',
+ *   version: 1,
+ *   baseCurrency: 'USD',
+ *   strategic: {
+ *     effectiveFrom: '2026-01-01',
+ *     targets: [
+ *       { group: { tag: 'equity' }, weight: 0.6 },
+ *       { group: { tag: 'fixed-income' }, weight: 0.3 },
+ *       { group: { assetClass: 'cash' }, weight: 0.1 },
+ *     ],
+ *   },
+ * });
+ * model.contentHash; // 'sha256:…'
+ * ```
+ */
+export function createModelPortfolio(definition) {
+    const functionName = 'createModelPortfolio';
+    const validated = requireModelPortfolioDefinition(functionName, 'definition', definition);
+    const artifact = {
+        kind: MODEL_PORTFOLIO_KIND,
+        schemaVersion: MODEL_PORTFOLIO_SCHEMA_VERSION,
+        ...validated,
+        contentHash: modelContentHash(validated),
+    };
+    return deepFreeze(artifact);
+}
+/** Validate a {@link ModelPortfolio} artifact, including that its hash matches its content. */
+export function requireModelPortfolio(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, ARTIFACT_KEYS);
+    const raw = value;
+    if (raw['kind'] !== MODEL_PORTFOLIO_KIND) {
+        throw new InputError(`${functionName}: ${path}.kind must be '${MODEL_PORTFOLIO_KIND}' (a createModelPortfolio artifact). Received ${describeInputValue(raw['kind'])}.`, {
+            code: ErrorCode.SnapshotKindMismatch,
+            context: { function: functionName, field: `${path}.kind` },
+        });
+    }
+    if (raw['schemaVersion'] !== MODEL_PORTFOLIO_SCHEMA_VERSION) {
+        throw new InputError(`${functionName}: ${path}.schemaVersion must be ${MODEL_PORTFOLIO_SCHEMA_VERSION}. Received ${describeInputValue(raw['schemaVersion'])}.`, {
+            code: ErrorCode.SnapshotUnsupportedVersion,
+            context: { function: functionName, field: `${path}.schemaVersion` },
+        });
+    }
+    requireIdentityString(functionName, `${path}.contentHash`, raw['contentHash']);
+    const body = { ...raw };
+    delete body['kind'];
+    delete body['schemaVersion'];
+    delete body['contentHash'];
+    const definition = requireModelPortfolioDefinition(functionName, path, body);
+    const expected = modelContentHash(definition);
+    if (expected !== raw['contentHash']) {
+        throw new DataError(`${functionName}: ${path}.contentHash (${String(raw['contentHash'])}) does not match the model's content (${expected}) — the artifact was edited after creation. Create a new version with createModelPortfolio.`, {
+            code: ErrorCode.ArtifactIdMismatch,
+            context: { function: functionName, field: `${path}.contentHash` },
+        });
+    }
+    return {
+        kind: MODEL_PORTFOLIO_KIND,
+        schemaVersion: MODEL_PORTFOLIO_SCHEMA_VERSION,
+        ...definition,
+        contentHash: expected,
+    };
+}
+/** Whether a value is a structurally valid, untampered model artifact (a predicate: never throws). */
+export function isModelPortfolio(value) {
+    try {
+        requireModelPortfolio('isModelPortfolio', 'value', value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate {@link PolicyLimits}. */
+export function requirePolicyLimits(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, LIMIT_KEYS);
+    const raw = value;
+    const out = {};
+    if (raw['maximumPositionWeight'] !== undefined) {
+        out.maximumPositionWeight = requireNonNegative(functionName, `${path}.maximumPositionWeight`, raw['maximumPositionWeight']);
+    }
+    if (raw['maximumGroupWeights'] !== undefined) {
+        requireArgumentArray(functionName, `${path}.maximumGroupWeights`, raw['maximumGroupWeights']);
+        const seen = new Set();
+        out.maximumGroupWeights = raw['maximumGroupWeights'].map((entry, index) => {
+            const entryPath = `${path}.maximumGroupWeights[${index}]`;
+            requireArgumentObject(functionName, entryPath, entry);
+            ensureKnownKeys(functionName, entryPath, entry, GROUP_LIMIT_KEYS);
+            const limit = entry;
+            const group = requireTargetGroup(functionName, `${entryPath}.group`, limit['group']);
+            const key = targetGroupKey(group);
+            if (seen.has(key))
+                outOfRange(functionName, entryPath, `${path}.maximumGroupWeights limits '${key}' twice.`);
+            seen.add(key);
+            return {
+                group,
+                maximumWeight: requireNonNegative(functionName, `${entryPath}.maximumWeight`, limit['maximumWeight']),
+            };
+        });
+    }
+    if (raw['maximumGrossLeverage'] !== undefined) {
+        requirePositiveNumberField(functionName, `${path}.maximumGrossLeverage`, raw['maximumGrossLeverage'], 'gross exposure ÷ NAV (1 = unlevered)');
+        out.maximumGrossLeverage = raw['maximumGrossLeverage'];
+    }
+    if (raw['maximumDrawdown'] !== undefined) {
+        const v = requireNonNegative(functionName, `${path}.maximumDrawdown`, raw['maximumDrawdown']);
+        if (v > 1)
+            outOfRange(functionName, `${path}.maximumDrawdown`, `${path}.maximumDrawdown is a decimal in [0, 1]. Received ${v}.`);
+        out.maximumDrawdown = v;
+    }
+    if (raw['maximumDailyLoss'] !== undefined) {
+        const v = requireNonNegative(functionName, `${path}.maximumDailyLoss`, raw['maximumDailyLoss']);
+        if (v > 1)
+            outOfRange(functionName, `${path}.maximumDailyLoss`, `${path}.maximumDailyLoss is a decimal in [0, 1]. Received ${v}.`);
+        out.maximumDailyLoss = v;
+    }
+    if (raw['maximumDaysToLiquidate'] !== undefined) {
+        requirePositiveNumberField(functionName, `${path}.maximumDaysToLiquidate`, raw['maximumDaysToLiquidate'], 'a liquidation horizon in days');
+        out.maximumDaysToLiquidate = raw['maximumDaysToLiquidate'];
+    }
+    if (raw['minimumSettledCash'] !== undefined) {
+        requireFiniteNumberField(functionName, `${path}.minimumSettledCash`, raw['minimumSettledCash']);
+        out.minimumSettledCash = raw['minimumSettledCash'];
+    }
+    return out;
+}
+/**
+ * Validate an {@link InvestmentPolicy}: closed keys, typed limits, targets inline XOR from a model
+ * artifact (whose hash is re-verified), identity lists without duplicates.
+ */
+export function requireInvestmentPolicy(functionName, path, value) {
+    requireArgumentObject(functionName, path, value);
+    ensureKnownKeys(functionName, path, value, POLICY_KEYS);
+    const raw = value;
+    const out = {};
+    if (raw['targets'] !== undefined && raw['model'] !== undefined) {
+        outOfRange(functionName, path, `${path} declares both targets and model — a policy's goals come from exactly one place.`);
+    }
+    if (raw['targets'] !== undefined) {
+        out.targets = requireAllocationTargets(functionName, `${path}.targets`, raw['targets']);
+    }
+    if (raw['model'] !== undefined) {
+        out.model = requireModelPortfolio(functionName, `${path}.model`, raw['model']);
+    }
+    if (raw['withinGroupAllocation'] !== undefined) {
+        out.withinGroupAllocation = requireLiteral(functionName, `${path}.withinGroupAllocation`, raw['withinGroupAllocation'], WITHIN_GROUP_ALLOCATIONS);
+    }
+    if (raw['driftBand'] !== undefined) {
+        out.driftBand = requireNonNegative(functionName, `${path}.driftBand`, raw['driftBand']);
+    }
+    if (raw['reviewCadenceDays'] !== undefined) {
+        requirePositiveNumberField(functionName, `${path}.reviewCadenceDays`, raw['reviewCadenceDays'], 'a review cadence in days');
+        out.reviewCadenceDays = raw['reviewCadenceDays'];
+    }
+    if (raw['maximumTurnover'] !== undefined) {
+        out.maximumTurnover = requireNonNegative(functionName, `${path}.maximumTurnover`, raw['maximumTurnover']);
+    }
+    if (raw['maximumEstimatedTransactionCost'] !== undefined) {
+        out.maximumEstimatedTransactionCost = requireNonNegative(functionName, `${path}.maximumEstimatedTransactionCost`, raw['maximumEstimatedTransactionCost']);
+    }
+    if (raw['minimumCash'] !== undefined) {
+        requireFiniteNumberField(functionName, `${path}.minimumCash`, raw['minimumCash']);
+        out.minimumCash = raw['minimumCash'];
+    }
+    if (raw['minimumCashWeight'] !== undefined) {
+        const v = requireNonNegative(functionName, `${path}.minimumCashWeight`, raw['minimumCashWeight']);
+        if (v > 1)
+            outOfRange(functionName, `${path}.minimumCashWeight`, `${path}.minimumCashWeight is a decimal of NAV in [0, 1]. Received ${v}.`);
+        out.minimumCashWeight = v;
+    }
+    if (raw['limits'] !== undefined) {
+        out.limits = requirePolicyLimits(functionName, `${path}.limits`, raw['limits']);
+    }
+    if (raw['allowedInstruments'] !== undefined) {
+        out.allowedInstruments = requireIdentityList(functionName, `${path}.allowedInstruments`, raw['allowedInstruments']);
+    }
+    if (raw['restrictedInstruments'] !== undefined) {
+        out.restrictedInstruments = requireIdentityList(functionName, `${path}.restrictedInstruments`, raw['restrictedInstruments']);
+    }
+    if (out.allowedInstruments !== undefined && out.restrictedInstruments !== undefined) {
+        const both = out.allowedInstruments.filter((id) => out.restrictedInstruments.includes(id));
+        if (both.length > 0) {
+            outOfRange(functionName, `${path}.restrictedInstruments`, `${path} both allows and restricts ${both.join(', ')}.`);
+        }
+    }
+    if (raw['allowedAccounts'] !== undefined) {
+        out.allowedAccounts = requireIdentityList(functionName, `${path}.allowedAccounts`, raw['allowedAccounts']);
+    }
+    if (raw['benchmark'] !== undefined) {
+        out.benchmark = requireBenchmark(functionName, `${path}.benchmark`, raw['benchmark']);
+    }
+    if (raw['performanceObjective'] !== undefined) {
+        if (typeof raw['performanceObjective'] !== 'string') {
+            throw new InputError(`${functionName}: ${path}.performanceObjective must be a string.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${path}.performanceObjective` },
+            });
+        }
+        out.performanceObjective = raw['performanceObjective'];
+    }
+    if (raw['contributionHandling'] !== undefined) {
+        out.contributionHandling = requireLiteral(functionName, `${path}.contributionHandling`, raw['contributionHandling'], CONTRIBUTION_HANDLINGS);
+    }
+    if (raw['withdrawalHandling'] !== undefined) {
+        out.withdrawalHandling = requireLiteral(functionName, `${path}.withdrawalHandling`, raw['withdrawalHandling'], WITHDRAWAL_HANDLINGS);
+    }
+    if (raw['incomeReinvestment'] !== undefined) {
+        out.incomeReinvestment = requireLiteral(functionName, `${path}.incomeReinvestment`, raw['incomeReinvestment'], INCOME_REINVESTMENTS);
+    }
+    if (raw['lotSelectionObjective'] !== undefined) {
+        requireIdentityString(functionName, `${path}.lotSelectionObjective`, raw['lotSelectionObjective']);
+        out.lotSelectionObjective = raw['lotSelectionObjective'];
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------------------------------
+// Resolution — which targets are effective at an instant
+// ---------------------------------------------------------------------------------------------------
+function interpolateTargets(from, to, fraction) {
+    const later = new Map(to.targets.map((t) => [targetGroupKey(t.group), t]));
+    return from.targets.map((target) => {
+        const next = later.get(targetGroupKey(target.group));
+        const out = {
+            group: target.group,
+            weight: target.weight + (next.weight - target.weight) * fraction,
+        };
+        const band = next.driftBand ?? target.driftBand;
+        if (band !== undefined)
+            out.driftBand = band;
+        return out;
+    });
+}
+const RESOLVE_KEYS = ['model', 'asOf'];
+/**
+ * The targets a model makes effective at `asOf`: the latest tactical set covering the instant,
+ * else the glide path (stepped or interpolated), else the strategic set. An instant before the
+ * strategic set is effective is a typed refusal — a model has no targets there.
+ *
+ * @example
+ * ```ts
+ * const effective = resolveModelTargets({ model, asOf: '2026-06-30' });
+ * effective.source; // 'strategic' | 'tactical' | 'glide-path'
+ * ```
+ */
+export function resolveModelTargets(input) {
+    const functionName = 'resolveModelTargets';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, RESOLVE_KEYS);
+    if (input.asOf === undefined) {
+        missingField(functionName, 'asOf', `asOf is required — a model's targets are dated, so the instant they are resolved at is a goal, not a default.\n  e.g. resolveModelTargets({ model, asOf: '2026-06-30' })`);
+    }
+    const { model, asOf } = input;
+    const validated = requireModelPortfolio(functionName, 'model', model);
+    const instant = requireInstant(functionName, 'asOf', asOf);
+    let winner = null;
+    for (const set of validated.tactical ?? []) {
+        const from = resolveAsOf(set.effectiveFrom, functionName);
+        const to = set.effectiveTo === undefined ? Infinity : resolveAsOf(set.effectiveTo, functionName);
+        if (from <= instant && instant < to && (winner === null || from >= winner.from)) {
+            winner = { set, from };
+        }
+    }
+    if (winner !== null) {
+        return { targets: winner.set.targets, source: 'tactical', effectiveFrom: winner.from };
+    }
+    if (validated.glidePath !== undefined) {
+        const points = validated.glidePath.points.map((set) => ({
+            set,
+            from: resolveAsOf(set.effectiveFrom, functionName),
+        }));
+        let index = -1;
+        for (let i = 0; i < points.length; i++)
+            if (points[i].from <= instant)
+                index = i;
+        if (index >= 0) {
+            const current = points[index];
+            const next = points[index + 1];
+            if (validated.glidePath.interpolation === 'linear' && next !== undefined) {
+                const fraction = (instant - current.from) / (next.from - current.from);
+                return {
+                    targets: interpolateTargets(current.set, next.set, fraction),
+                    source: 'glide-path',
+                    effectiveFrom: current.from,
+                    interpolation: { from: current.from, to: next.from, fraction },
+                };
+            }
+            return { targets: current.set.targets, source: 'glide-path', effectiveFrom: current.from };
+        }
+    }
+    const strategicFrom = resolveAsOf(validated.strategic.effectiveFrom, functionName);
+    if (instant < strategicFrom) {
+        outOfRange(functionName, 'asOf', `no target set is effective at ${epochMsToUtcDate(instant)} — the strategic set of model '${validated.modelId}' v${validated.version} starts ${epochMsToUtcDate(strategicFrom)}. A model has no goals before its first dated set.`);
+    }
+    return {
+        targets: validated.strategic.targets,
+        source: 'strategic',
+        effectiveFrom: strategicFrom,
+    };
+}
+/**
+ * The targets a POLICY makes effective at `asOf`: inline targets verbatim, or the model's
+ * resolution. A policy without targets is a typed refusal from the caller that needs them.
+ */
+export function resolvePolicyTargets(functionName, policy, asOf) {
+    if (policy.targets !== undefined) {
+        return { targets: policy.targets, source: 'inline', effectiveFrom: null };
+    }
+    if (policy.model !== undefined)
+        return resolveModelTargets({ model: policy.model, asOf });
+    throw new InputError(`${functionName}: policy declares no targets — give policy.targets or policy.model (a createModelPortfolio artifact). Missing goals are never defaulted.\n  e.g. ${POLICY_EXAMPLE}`, {
+        code: ErrorCode.InputMissingField,
+        context: { function: functionName, field: 'policy.targets' },
+    });
+}
+// ---------------------------------------------------------------------------------------------------
+// Expansion — group targets to instrument targets
+// ---------------------------------------------------------------------------------------------------
+/** The classification group keys an instrument belongs to (`'assetClass:equity'`, `'tag:tech'`, …). */
+export function instrumentGroupKeys(instrumentId, classification, currency) {
+    const keys = [`instrumentId:${instrumentId}`];
+    if (currency !== undefined)
+        keys.push(`currency:${currency}`);
+    if (classification?.assetClass !== undefined)
+        keys.push(`assetClass:${classification.assetClass}`);
+    if (classification?.underlying !== undefined)
+        keys.push(`underlying:${classification.underlying}`);
+    if (classification?.strategy !== undefined)
+        keys.push(`strategy:${classification.strategy}`);
+    for (const tag of classification?.tags ?? [])
+        keys.push(`tag:${tag}`);
+    return keys;
+}
+/** Leaf instrument weights of a sleeve subtree, each scaled by the path's within-parent weights. */
+function sleeveLeafWeights(sleeveId, sleeves) {
+    const out = new Map();
+    const sleeve = sleeves.find((s) => s.sleeveId === sleeveId);
+    if (sleeve.members !== undefined) {
+        for (const member of sleeve.members) {
+            out.set(member.instrumentId, (out.get(member.instrumentId) ?? 0) + member.weight);
+        }
+        return out;
+    }
+    for (const child of sleeves.filter((s) => s.parentSleeveId === sleeveId)) {
+        for (const [instrumentId, weight] of sleeveLeafWeights(child.sleeveId, sleeves)) {
+            out.set(instrumentId, (out.get(instrumentId) ?? 0) + weight * child.weightWithinParent);
+        }
+    }
+    return out;
+}
+/**
+ * Expand resolved group targets to per-instrument target weights under the ONE resolution law:
+ *
+ * - `instrumentId` targets bind directly; `sleeveId` targets flow down the sleeve tree;
+ * - classification/currency targets bind to the universe members that carry the group and split
+ *   by `withinGroupAllocation` (REQUIRED when a group has more than one member — never guessed);
+ * - an instrument named by two targets is a CONFLICT (both unresolved); a group with no members
+ *   is unresolved; a risk-budget target is unresolved (needs a covariance — risk side);
+ * - `{ assetClass: 'cash' }` is the cash target. When the declared weights sum to 1, every
+ *   uncovered instrument (and a missing cash target) has an IMPLIED target of 0 and is flagged
+ *   `implied`; when they sum to less than 1 the remainder is undeclared and the uncovered
+ *   instruments are unresolved — missing goals do not become secret defaults.
+ */
+export function expandTargets(functionName, input) {
+    const warnings = [];
+    const unresolved = [];
+    const groupTargets = [];
+    const perInstrument = new Map();
+    const universe = [...new Set(input.universe)].sort();
+    const universeKeys = new Map(universe.map((id) => [
+        id,
+        new Set(instrumentGroupKeys(id, ownValue(input.instrumentClassification, id), ownValue(input.instrumentCurrency, id))),
+    ]));
+    let cashTarget = null;
+    let declaredWeightTotal = 0;
+    const bind = (instrumentId, weight, band, source) => {
+        const existing = perInstrument.get(instrumentId);
+        if (existing === undefined) {
+            perInstrument.set(instrumentId, { weight, band, sources: [source] });
+            return;
+        }
+        existing.weight += weight;
+        existing.sources.push(source);
+        if (band !== null)
+            existing.band = existing.band === null ? band : Math.min(existing.band, band);
+    };
+    for (const target of input.targets) {
+        const key = targetGroupKey(target.group);
+        const band = target.driftBand ?? input.defaultDriftBand ?? null;
+        if (target.riskBudget !== undefined) {
+            unresolved.push({
+                key,
+                group: target.group,
+                reason: `risk budget ${target.riskBudget} needs a covariance to become weights — resolve it on the risk side (@insiderfinance/totalfinance/risk) and restate as weight targets.`,
+            });
+            continue;
+        }
+        const weight = target.weight;
+        declaredWeightTotal += weight;
+        if (isCashTargetGroup(target.group)) {
+            cashTarget = { targetWeight: weight, driftBand: band, implied: false };
+            groupTargets.push({
+                key,
+                group: target.group,
+                targetWeight: weight,
+                driftBand: band,
+                members: [],
+            });
+            continue;
+        }
+        if (target.group.instrumentId !== undefined) {
+            const id = target.group.instrumentId;
+            if (!universeKeys.has(id)) {
+                universe.push(id);
+                universeKeys.set(id, new Set(instrumentGroupKeys(id, ownValue(input.instrumentClassification, id), ownValue(input.instrumentCurrency, id))));
+            }
+            bind(id, weight, band, key);
+            groupTargets.push({
+                key,
+                group: target.group,
+                targetWeight: weight,
+                driftBand: band,
+                members: [id],
+            });
+            continue;
+        }
+        if (target.group.sleeveId !== undefined) {
+            const leaves = sleeveLeafWeights(target.group.sleeveId, input.sleeves);
+            const members = [...leaves.keys()].sort();
+            for (const id of members) {
+                if (!universeKeys.has(id)) {
+                    universe.push(id);
+                    universeKeys.set(id, new Set(instrumentGroupKeys(id, ownValue(input.instrumentClassification, id), ownValue(input.instrumentCurrency, id))));
+                }
+                bind(id, weight * leaves.get(id), band, key);
+            }
+            groupTargets.push({
+                key,
+                group: target.group,
+                targetWeight: weight,
+                driftBand: band,
+                members,
+            });
+            continue;
+        }
+        // Classification / currency dimension.
+        const members = universe.filter((id) => universeKeys.get(id).has(key)).sort();
+        if (members.length === 0) {
+            unresolved.push({
+                key,
+                group: target.group,
+                reason: `no instrument in the universe carries '${key}' — declare the group's members through instrumentClassification (or a sleeve), or add an instrumentId target.`,
+            });
+            groupTargets.push({
+                key,
+                group: target.group,
+                targetWeight: weight,
+                driftBand: band,
+                members: [],
+            });
+            continue;
+        }
+        if (members.length === 1) {
+            bind(members[0], weight, band, key);
+        }
+        else if (input.withinGroupAllocation === undefined) {
+            unresolved.push({
+                key,
+                group: target.group,
+                reason: `'${key}' resolves to ${members.length} instruments (${members.join(', ')}) and the policy declares no withinGroupAllocation ('proportional-to-current' or 'equal') — how a group target splits is a goal, not a default.`,
+            });
+            groupTargets.push({
+                key,
+                group: target.group,
+                targetWeight: weight,
+                driftBand: band,
+                members,
+            });
+            continue;
+        }
+        else {
+            const current = members.map((id) => Math.abs(ownValue(input.currentWeights, id) ?? 0));
+            const currentTotal = sum(current);
+            const equal = input.withinGroupAllocation === 'equal' || currentTotal <= WEIGHT_TOLERANCE;
+            if (input.withinGroupAllocation === 'proportional-to-current' &&
+                currentTotal <= WEIGHT_TOLERANCE) {
+                warnings.push(`'${key}' has no current holdings to split proportionally; its ${members.length} members are split equally.`);
+            }
+            members.forEach((id, index) => {
+                const share = equal ? 1 / members.length : current[index] / currentTotal;
+                bind(id, weight * share, band, key);
+            });
+        }
+        groupTargets.push({ key, group: target.group, targetWeight: weight, driftBand: band, members });
+    }
+    // Conflicts: an instrument bound by two different targets is two goals for one holding.
+    const conflicted = new Set();
+    for (const [id, entry] of perInstrument) {
+        if (entry.sources.length > 1) {
+            conflicted.add(id);
+            for (const source of entry.sources) {
+                if (!unresolved.some((u) => u.key === source)) {
+                    const group = groupTargets.find((g) => g.key === source).group;
+                    unresolved.push({
+                        key: source,
+                        group,
+                        reason: `'${id}' is targeted by ${entry.sources.join(' and ')} — overlapping targets on one instrument conflict; restate them on one dimension.`,
+                    });
+                }
+            }
+            perInstrument.delete(id);
+        }
+    }
+    const covered = new Set(perInstrument.keys());
+    const fullyDeclared = Math.abs(declaredWeightTotal - 1) <= WEIGHT_TOLERANCE;
+    const instrumentTargets = [];
+    for (const id of universe) {
+        const entry = perInstrument.get(id);
+        if (entry !== undefined) {
+            instrumentTargets.push({
+                instrumentId: id,
+                targetWeight: entry.weight,
+                driftBand: entry.band,
+                sourceGroups: entry.sources,
+                implied: false,
+            });
+            continue;
+        }
+        if (covered.has(id) || conflicted.has(id))
+            continue;
+        if (fullyDeclared) {
+            instrumentTargets.push({
+                instrumentId: id,
+                targetWeight: 0,
+                driftBand: input.defaultDriftBand ?? null,
+                sourceGroups: [],
+                implied: true,
+            });
+        }
+        else if (!unresolved.some((u) => u.key === `instrumentId:${id}`)) {
+            unresolved.push({
+                key: `instrumentId:${id}`,
+                group: { instrumentId: id },
+                reason: `'${id}' is covered by no target and the declared targets sum to ${readable(declaredWeightTotal)} of NAV, not 1 — declare the remaining ${readable(1 - declaredWeightTotal)} (a cash target, or targets naming this holding).`,
+            });
+        }
+    }
+    if (cashTarget === null && fullyDeclared) {
+        cashTarget = { targetWeight: 0, driftBand: input.defaultDriftBand ?? null, implied: true };
+    }
+    else if (cashTarget === null &&
+        declaredWeightTotal < 1 - WEIGHT_TOLERANCE &&
+        universe.every((id) => perInstrument.has(id))) {
+        unresolved.push({
+            key: `assetClass:${CASH_ASSET_CLASS}`,
+            group: { assetClass: CASH_ASSET_CLASS },
+            reason: `the declared targets sum to ${readable(declaredWeightTotal)} of NAV and there is no cash target — declare { assetClass: 'cash' } for the remaining ${readable(1 - declaredWeightTotal)}, or targets that use it.`,
+        });
+    }
+    if (declaredWeightTotal > 1 + WEIGHT_TOLERANCE) {
+        unresolved.push({
+            key: 'targets',
+            group: { assetClass: CASH_ASSET_CLASS },
+            reason: `the declared targets sum to ${readable(declaredWeightTotal)} of NAV across dimensions — more than the whole portfolio; overlapping dimensions must not double-count.`,
+        });
+    }
+    instrumentTargets.sort((a, b) => a.instrumentId < b.instrumentId ? -1 : a.instrumentId > b.instrumentId ? 1 : 0);
+    return { instrumentTargets, groupTargets, cashTarget, declaredWeightTotal, unresolved, warnings };
+}
+/** The policy grammar's conventions, echoed by every consumer. */
+export const POLICY_CONVENTIONS_VERSION = CONVENTIONS_VERSION;
+//# sourceMappingURL=policy-grammar.js.map