@insiderfinance/totalfinance 0.1.0

package/modules/research/src/universe.ts

@@ -0,0 +1,494 @@
+/**
+ * Point-in-time universe vocabulary (Stage 4.6, FC8 Decision 3) — owned here because research owns
+ * universe identity and eligibility; a simulator reads these and never redefines them.
+ *
+ * - A universe is a HISTORY of membership intervals, not a snapshot: a name is a member from
+ *   `fromTimestampMs` (inclusive) until `toTimestampMs` (exclusive). An exit says why, and a
+ *   `delisted` exit carries the return a holder earned from the last available price to the exit
+ *   so a backtest can book the fact instead of silently surviving it.
+ * - Eligibility at an instant is the SAME law screening applies: an observation is visible only
+ *   when its `availableTimestampMs` is at or before the decision instant (minus an explicit lag in
+ *   trading sessions), and one instrument resolves to its latest available version.
+ *
+ * Everything is deterministic, clock-free, and JSON-safe; nothing mutates a caller array.
+ */
+
+import {
+  ErrorCode,
+  InputError,
+  ensureKnownKeys,
+  requireArgumentObject,
+  type EpochMs,
+} from '@totalfinance/core';
+import {
+  type FieldDefinition,
+  type UniverseObservation,
+  requireBoundaryName,
+  requireFieldDefinitions,
+  requirePathLabel,
+  requireUniverseObservations,
+} from './observations.js';
+import { resolveLatestAvailableObservations } from './point-in-time.js';
+
+// ---------------------------------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------------------------------
+
+export type UniverseExitReason = 'removed' | 'delisted' | 'merged' | 'other';
+
+/** One membership interval of one instrument. Half-open: `[fromTimestampMs, toTimestampMs)`. */
+export interface UniverseMember {
+  instrumentId: string;
+  /** First instant the name is a member (inclusive). */
+  fromTimestampMs: EpochMs;
+  /** First instant it is no longer a member (exclusive); omitted = still a member. */
+  toTimestampMs?: EpochMs;
+  exitReason?: UniverseExitReason;
+  /**
+   * The simple return a holder earned from the last available price to the exit — a delisting
+   * return (−1 for a total loss). Required by a simulator when `exitReason` is `'delisted'` and a
+   * position is open; recorded here so the fact travels with the universe, not the strategy.
+   */
+  delistingReturn?: number;
+}
+
+export interface UniverseHistory {
+  universeId: string;
+  members: readonly UniverseMember[];
+}
+
+const HISTORY_KEYS = ['universeId', 'members'] as const;
+const MEMBER_KEYS = [
+  'instrumentId',
+  'fromTimestampMs',
+  'toTimestampMs',
+  'exitReason',
+  'delistingReturn',
+] as const;
+const EXIT_REASONS: readonly UniverseExitReason[] = ['removed', 'delisted', 'merged', 'other'];
+
+const EXAMPLE_HISTORY =
+  "{ universeId: 'us-large-cap', members: [{ instrumentId: 'AAPL', fromTimestampMs: 1735689600000 }, { instrumentId: 'XYZ', fromTimestampMs: 1735689600000, toTimestampMs: 1751328000000, exitReason: 'delisted', delistingReturn: -0.4 }] }";
+
+// ---------------------------------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------------------------------
+
+function isEpochMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Validate a {@link UniverseHistory} at a public boundary: a closed record whose members are
+ * closed records with finite instants, a half-open non-empty interval each, a declared exit
+ * reason whenever an exit instant is given, a finite delisting return ≥ −1 only beside an exit,
+ * and no two overlapping intervals for one instrument (a name cannot be a member twice at once).
+ */
+export function requireUniverseHistory(
+  functionName: string,
+  label: string,
+  history: UniverseHistory,
+): void {
+  requireBoundaryName(functionName);
+  requirePathLabel(functionName, 'label', label);
+  requireArgumentObject(functionName, label, history);
+  ensureKnownKeys(functionName, label, history, HISTORY_KEYS);
+  if (typeof history.universeId !== 'string' || history.universeId.length === 0) {
+    throw new InputError(
+      `${functionName}: ${label}.universeId must be a non-empty string — a universe without an identity is a list without a source.\n  e.g. ${EXAMPLE_HISTORY}`,
+      { code: ErrorCode.InputWrongType, context: { field: `${label}.universeId` } },
+    );
+  }
+  if (!Array.isArray(history.members)) {
+    throw new InputError(
+      `${functionName}: ${label}.members must be an array of membership intervals (it may be empty).\n  e.g. ${EXAMPLE_HISTORY}`,
+      { code: ErrorCode.InputWrongType, context: { field: `${label}.members` } },
+    );
+  }
+  const intervals = new Map<string, Array<{ from: number; to: number; path: string }>>();
+  history.members.forEach((member, index) => {
+    const path = `${label}.members[${index}]`;
+    requireArgumentObject(functionName, path, member);
+    ensureKnownKeys(functionName, path, member, MEMBER_KEYS);
+    if (typeof member.instrumentId !== 'string' || member.instrumentId.length === 0) {
+      throw new InputError(`${functionName}: ${path}.instrumentId must be a non-empty string.`, {
+        code: ErrorCode.InputWrongType,
+        context: { field: `${path}.instrumentId` },
+      });
+    }
+    if (!isEpochMs(member.fromTimestampMs)) {
+      throw new InputError(
+        `${functionName}: ${path}.fromTimestampMs must be a finite epoch-ms number (the first instant the name is a member).`,
+        { code: ErrorCode.InputWrongType, context: { field: `${path}.fromTimestampMs` } },
+      );
+    }
+    let to = Number.POSITIVE_INFINITY;
+    if (member.toTimestampMs !== undefined) {
+      if (!isEpochMs(member.toTimestampMs)) {
+        throw new InputError(
+          `${functionName}: ${path}.toTimestampMs must be a finite epoch-ms number (the first instant the name is NOT a member) or omitted while it is still a member.`,
+          { code: ErrorCode.InputWrongType, context: { field: `${path}.toTimestampMs` } },
+        );
+      }
+      if (member.toTimestampMs <= member.fromTimestampMs) {
+        throw new InputError(
+          `${functionName}: ${path}.toTimestampMs (${member.toTimestampMs}) must be after fromTimestampMs (${member.fromTimestampMs}) — the interval is half-open [from, to) and cannot be empty.`,
+          { code: ErrorCode.InputOutOfRange, context: { field: `${path}.toTimestampMs` } },
+        );
+      }
+      to = member.toTimestampMs;
+    }
+    if (member.exitReason !== undefined) {
+      if (!EXIT_REASONS.includes(member.exitReason)) {
+        throw new InputError(
+          `${functionName}: ${path}.exitReason must be one of ${EXIT_REASONS.map((r) => `'${r}'`).join(' | ')}. Received ${JSON.stringify(member.exitReason)}.`,
+          { code: ErrorCode.InputInvalidEnum, context: { field: `${path}.exitReason` } },
+        );
+      }
+      if (member.toTimestampMs === undefined) {
+        throw new InputError(
+          `${functionName}: ${path}.exitReason is given but ${path}.toTimestampMs is not — an exit needs an exit instant.`,
+          { code: ErrorCode.InputMissingField, context: { field: `${path}.toTimestampMs` } },
+        );
+      }
+    }
+    if (member.delistingReturn !== undefined) {
+      if (typeof member.delistingReturn !== 'number' || !Number.isFinite(member.delistingReturn)) {
+        throw new InputError(
+          `${functionName}: ${path}.delistingReturn must be a finite simple return (−1 is a total loss).`,
+          { code: ErrorCode.InputWrongType, context: { field: `${path}.delistingReturn` } },
+        );
+      }
+      if (member.delistingReturn < -1) {
+        throw new InputError(
+          `${functionName}: ${path}.delistingReturn (${member.delistingReturn}) is below −1 — a holder cannot lose more than the position.`,
+          { code: ErrorCode.InputOutOfRange, context: { field: `${path}.delistingReturn` } },
+        );
+      }
+      if (member.exitReason !== 'delisted') {
+        throw new InputError(
+          `${functionName}: ${path}.delistingReturn is given but ${path}.exitReason is ${member.exitReason === undefined ? 'absent' : `'${member.exitReason}'`} — a delisting return describes a 'delisted' exit only.`,
+          { code: ErrorCode.InputOutOfRange, context: { field: `${path}.delistingReturn` } },
+        );
+      }
+    }
+    const list = intervals.get(member.instrumentId) ?? [];
+    for (const other of list) {
+      if (member.fromTimestampMs < other.to && other.from < to) {
+        throw new InputError(
+          `${functionName}: ${path} overlaps ${other.path} for '${member.instrumentId}' — a name cannot be a member of one universe twice at the same instant; split the history into disjoint intervals.`,
+          { code: ErrorCode.InputOutOfRange, context: { field: path } },
+        );
+      }
+    }
+    list.push({ from: member.fromTimestampMs, to, path });
+    intervals.set(member.instrumentId, list);
+  });
+}
+
+// ---------------------------------------------------------------------------------------------------
+// universeMembershipAt
+// ---------------------------------------------------------------------------------------------------
+
+export interface UniverseMembershipAtInput {
+  universeHistory: UniverseHistory;
+  /** The decision instant. */
+  asOf: EpochMs;
+  /**
+   * The previous decision instant. When given, `additions` and `exits` describe what changed in
+   * `(previousAsOf, asOf]`; when omitted both are empty and only `instrumentIds` is meaningful.
+   */
+  previousAsOf?: EpochMs;
+}
+
+export interface UniverseExit {
+  instrumentId: string;
+  exitTimestampMs: EpochMs;
+  exitReason: UniverseExitReason | null;
+  delistingReturn: number | null;
+}
+
+export interface UniverseMembershipAtResult {
+  assumptions: {
+    universeId: string;
+    asOf: EpochMs;
+    previousAsOf: EpochMs | null;
+    membershipRule: 'fromTimestampMs <= asOf < toTimestampMs';
+  };
+  diagnostics: {
+    warnings: string[];
+    memberCount: number;
+    additionCount: number;
+    exitCount: number;
+  };
+  /** Members at `asOf`, `instrumentId` ascending. */
+  instrumentIds: string[];
+  /** Names whose membership began in `(previousAsOf, asOf]`, ascending. */
+  additions: string[];
+  /** Names whose membership ended in `(previousAsOf, asOf]`, ascending by id then instant. */
+  exits: UniverseExit[];
+}
+
+const MEMBERSHIP_KEYS = ['universeHistory', 'asOf', 'previousAsOf'] as const;
+
+/**
+ * Who is in the universe at an instant, and — against a previous instant — who joined and who
+ * left (with the exit reason and any delisting return). The membership rule is the half-open
+ * interval; ties are impossible because one instant is either inside an interval or not.
+ */
+export function universeMembershipAt(input: UniverseMembershipAtInput): UniverseMembershipAtResult {
+  const functionName = 'universeMembershipAt';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, MEMBERSHIP_KEYS);
+  requireUniverseHistory(functionName, 'input.universeHistory', input.universeHistory);
+  if (!isEpochMs(input.asOf)) {
+    throw new InputError(`${functionName}: input.asOf must be a finite epoch-ms number.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'asOf' },
+    });
+  }
+  if (input.previousAsOf !== undefined) {
+    if (!isEpochMs(input.previousAsOf)) {
+      throw new InputError(
+        `${functionName}: input.previousAsOf must be a finite epoch-ms number.`,
+        {
+          code: ErrorCode.InputWrongType,
+          context: { field: 'previousAsOf' },
+        },
+      );
+    }
+    if (input.previousAsOf >= input.asOf) {
+      throw new InputError(
+        `${functionName}: input.previousAsOf (${input.previousAsOf}) must be before input.asOf (${input.asOf}) — the change window is (previousAsOf, asOf].`,
+        { code: ErrorCode.InputOutOfRange, context: { field: 'previousAsOf' } },
+      );
+    }
+  }
+  const { asOf } = input;
+  const previous = input.previousAsOf;
+  const members = new Set<string>();
+  const additions = new Set<string>();
+  const exits: UniverseExit[] = [];
+  for (const member of input.universeHistory.members) {
+    const to = member.toTimestampMs ?? Number.POSITIVE_INFINITY;
+    if (member.fromTimestampMs <= asOf && asOf < to) members.add(member.instrumentId);
+    if (previous !== undefined) {
+      if (member.fromTimestampMs > previous && member.fromTimestampMs <= asOf) {
+        additions.add(member.instrumentId);
+      }
+      if (to > previous && to <= asOf) {
+        exits.push({
+          instrumentId: member.instrumentId,
+          exitTimestampMs: to,
+          exitReason: member.exitReason ?? null,
+          delistingReturn: member.delistingReturn ?? null,
+        });
+      }
+    }
+  }
+  const byId = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  exits.sort(
+    (a, b) => byId(a.instrumentId, b.instrumentId) || a.exitTimestampMs - b.exitTimestampMs,
+  );
+  const warnings: string[] = [];
+  for (const exit of exits) {
+    if (exit.exitReason === 'delisted' && exit.delistingReturn === null) {
+      warnings.push(
+        `'${exit.instrumentId}' was delisted at ${exit.exitTimestampMs} without a delistingReturn — a simulator holding it must refuse rather than assume the exit value.`,
+      );
+    }
+  }
+  return {
+    assumptions: {
+      universeId: input.universeHistory.universeId,
+      asOf,
+      previousAsOf: previous ?? null,
+      membershipRule: 'fromTimestampMs <= asOf < toTimestampMs',
+    },
+    diagnostics: {
+      warnings,
+      memberCount: members.size,
+      additionCount: additions.size,
+      exitCount: exits.length,
+    },
+    instrumentIds: [...members].sort(byId),
+    additions: [...additions].sort(byId),
+    exits,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// eligibleObservationsAt
+// ---------------------------------------------------------------------------------------------------
+
+export interface EligibilityLag {
+  /** How many trading sessions before `asOf` the data must have been available. */
+  tradingSessions: number;
+  /**
+   * The session instants the caller's dataset knows, ascending — the lag counts sessions in this
+   * index, never calendar days, so a weekend or holiday is not a session.
+   */
+  sessionTimestamps: readonly EpochMs[];
+}
+
+export interface EligibleObservationsAtInput {
+  observations: readonly UniverseObservation[];
+  fieldDefinitions: readonly FieldDefinition[];
+  asOf: EpochMs;
+  /** Omitted = no lag: availability at or before `asOf` is enough. */
+  lag?: EligibilityLag;
+  /** When given, only members of this universe at `asOf` are eligible. */
+  universeHistory?: UniverseHistory;
+}
+
+export interface EligibleObservationsAtResult {
+  assumptions: {
+    asOf: EpochMs;
+    /** The instant availability is measured against: `asOf`, or the lagged session instant. */
+    availabilityCutoffMs: EpochMs;
+    lagTradingSessions: number;
+    universeId: string | null;
+    versionResolution: 'latest available at or before the cutoff per instrument';
+  };
+  diagnostics: {
+    warnings: string[];
+    suppliedCount: number;
+    eligibleCount: number;
+    excludedCount: number;
+    exclusionReasons: Record<string, number>;
+  };
+  /** One observation per eligible instrument, `instrumentId` ascending. */
+  observations: UniverseObservation[];
+}
+
+const ELIGIBLE_KEYS = [
+  'observations',
+  'fieldDefinitions',
+  'asOf',
+  'lag',
+  'universeHistory',
+] as const;
+const LAG_KEYS = ['tradingSessions', 'sessionTimestamps'] as const;
+/** The library-wide ceiling on a count that sizes work (the count-safety law). */
+const MAXIMUM_LAG_SESSIONS = 100_000;
+
+/**
+ * The observations a decision at `asOf` may see: available at or before the cutoff (an explicit
+ * session lag moves the cutoff back through the caller's session index), the latest version per
+ * instrument, and — when a universe history is given — members at `asOf` only. Shifting a row's
+ * `availableTimestampMs` past the cutoff removes it; the acceptance law every FC3 screen already
+ * satisfies, exposed for the simulators.
+ */
+export function eligibleObservationsAt(
+  input: EligibleObservationsAtInput,
+): EligibleObservationsAtResult {
+  const functionName = 'eligibleObservationsAt';
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, ELIGIBLE_KEYS);
+  const definitions = requireFieldDefinitions(functionName, input.fieldDefinitions);
+  requireUniverseObservations(functionName, input.observations, definitions);
+  if (!isEpochMs(input.asOf)) {
+    throw new InputError(`${functionName}: input.asOf must be a finite epoch-ms number.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'asOf' },
+    });
+  }
+  let cutoff = input.asOf;
+  let lagSessions = 0;
+  if (input.lag !== undefined) {
+    requireArgumentObject(functionName, 'input.lag', input.lag);
+    ensureKnownKeys(functionName, 'input.lag', input.lag, LAG_KEYS);
+    const { tradingSessions, sessionTimestamps } = input.lag;
+    if (
+      !Number.isSafeInteger(tradingSessions) ||
+      tradingSessions < 0 ||
+      tradingSessions > MAXIMUM_LAG_SESSIONS
+    ) {
+      throw new InputError(
+        `${functionName}: input.lag.tradingSessions must be an integer in [0, ${MAXIMUM_LAG_SESSIONS}]. Received ${String(tradingSessions)}.`,
+        { code: ErrorCode.InputOutOfRange, context: { field: 'lag.tradingSessions' } },
+      );
+    }
+    if (!Array.isArray(sessionTimestamps)) {
+      throw new InputError(
+        `${functionName}: input.lag.sessionTimestamps must be an ascending array of session instants — a lag counts sessions in the dataset's own index, never calendar days.`,
+        { code: ErrorCode.InputWrongType, context: { field: 'lag.sessionTimestamps' } },
+      );
+    }
+    sessionTimestamps.forEach((instant, index) => {
+      if (!isEpochMs(instant)) {
+        throw new InputError(
+          `${functionName}: input.lag.sessionTimestamps[${index}] must be a finite epoch-ms number.`,
+          { code: ErrorCode.InputWrongType, context: { field: `lag.sessionTimestamps[${index}]` } },
+        );
+      }
+      if (index > 0 && instant <= (sessionTimestamps[index - 1] as number)) {
+        throw new InputError(
+          `${functionName}: input.lag.sessionTimestamps must be strictly ascending; [${index}] (${instant}) does not follow [${index - 1}] (${String(sessionTimestamps[index - 1])}).`,
+          {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: `lag.sessionTimestamps[${index}]` },
+          },
+        );
+      }
+    });
+    lagSessions = tradingSessions;
+    if (tradingSessions > 0) {
+      // The session at or before asOf, then `tradingSessions` sessions earlier in the index.
+      let position = -1;
+      for (let i = 0; i < sessionTimestamps.length; i += 1) {
+        if ((sessionTimestamps[i] as number) <= input.asOf) position = i;
+        else break;
+      }
+      const lagged = position - tradingSessions;
+      if (position < 0 || lagged < 0) {
+        throw new InputError(
+          `${functionName}: a lag of ${tradingSessions} trading session${tradingSessions === 1 ? '' : 's'} before asOf (${input.asOf}) reaches before the first session in input.lag.sessionTimestamps — extend the session index or lower the lag.`,
+          { code: ErrorCode.InputOutOfRange, context: { field: 'lag.tradingSessions' } },
+        );
+      }
+      cutoff = sessionTimestamps[lagged] as number;
+    }
+  }
+  let universeId: string | null = null;
+  let members: Set<string> | null = null;
+  if (input.universeHistory !== undefined) {
+    const membership = universeMembershipAt({
+      universeHistory: input.universeHistory,
+      asOf: input.asOf,
+    });
+    universeId = membership.assumptions.universeId;
+    members = new Set(membership.instrumentIds);
+  }
+  const exclusionReasons: Record<string, number> = {};
+  const addExclusion = (reason: string): void => {
+    exclusionReasons[reason] = (exclusionReasons[reason] ?? 0) + 1;
+  };
+  const resolved = resolveLatestAvailableObservations(input.observations, cutoff, addExclusion);
+  const eligible =
+    members === null
+      ? resolved
+      : resolved.filter((observation) => {
+          const isMember = members.has(observation.instrumentId);
+          if (!isMember) addExclusion('not-a-universe-member-at-asOf');
+          return isMember;
+        });
+  const excludedCount = Object.values(exclusionReasons).reduce((sum, count) => sum + count, 0);
+  return {
+    assumptions: {
+      asOf: input.asOf,
+      availabilityCutoffMs: cutoff,
+      lagTradingSessions: lagSessions,
+      universeId,
+      versionResolution: 'latest available at or before the cutoff per instrument',
+    },
+    diagnostics: {
+      warnings: [],
+      suppliedCount: input.observations.length,
+      eligibleCount: eligible.length,
+      excludedCount,
+      exclusionReasons,
+    },
+    observations: eligible,
+  };
+}

package/modules/risk/dist/attribution.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Return attribution (spec: `docs/specs/attribution.md`, roadmap Tier 2). Two classic decompositions
+ * that split a realized return into named, additive pieces which reconstruct the total EXACTLY:
+ *
+ * - `factorAttribution` — regress a return series on observable factor returns and split the realized
+ *   return into a contribution per factor plus a specific (alpha/skill) residual. Because OLS residuals
+ *   sum to zero with an intercept, `totalReturn = specificReturn + Σ contributions` to machine precision.
+ * - `brinsonAttribution` — split a portfolio's active return vs a benchmark into allocation, selection,
+ *   and interaction, with `allocation + selection + interaction = activeReturn` exactly.
+ *
+ * The statistical (PCA) factor model lives separately in `factor.ts` (`pca`/`factorExposure`).
+ */
+import { type Diagnostics } from '../../core/dist/index.js';
+/** One observable factor's return series. */
+export interface FactorSeries {
+    name: string;
+    /** Per-period factor returns, aligned to the subject `returns`. */
+    returns: ArrayLike<number>;
+}
+/** Inputs for {@link factorAttribution}. */
+export interface FactorAttributionInput {
+    /** The asset/portfolio return series to attribute. */
+    returns: ArrayLike<number>;
+    /** Observable factor return series (each aligned to `returns`). */
+    factors: FactorSeries[];
+    /** Per-period risk-free rate subtracted from `returns` first; default 0. */
+    riskFreeRate?: number;
+}
+/** A factor's exposure and its contribution to the realized return. */
+export interface FactorContribution {
+    name: string;
+    /** Exposure / loading `β_k`. */
+    beta: number;
+    /** t-statistic of the exposure. */
+    tStatistic: number;
+    /** Cumulative return attributable to the factor: `β_k · Σ(factor returns)`. */
+    contribution: number;
+}
+/** The factor attribution. */
+export interface FactorAttribution {
+    factors: FactorContribution[];
+    /** Per-period specific return (the OLS intercept). */
+    alpha: number;
+    /** Cumulative specific return `n·alpha` — the part no factor explains. */
+    specificReturn: number;
+    /** Total of the (excess, if `riskFreeRate` given) return series = `specificReturn + Σ contributions`. */
+    totalReturn: number;
+    rSquared: number;
+    adjustedRSquared: number;
+    observations: number;
+    assumptions: {
+        conventionsVersion: string;
+        riskFreeRate: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Attribute a return series to observable factors by OLS regression, splitting the realized return into
+ * a contribution per factor plus a specific (alpha) residual — a decomposition that reconstructs the
+ * total exactly. See `docs/specs/attribution.md`.
+ */
+export declare function factorAttribution(input: FactorAttributionInput): FactorAttribution;
+/** One segment (sector/bucket) of a Brinson attribution. */
+export interface BrinsonSegment {
+    name: string;
+    portfolioWeight: number;
+    benchmarkWeight: number;
+    portfolioReturn: number;
+    benchmarkReturn: number;
+}
+/** The allocation / selection / interaction effects for one segment. */
+export interface SegmentEffect {
+    name: string;
+    allocation: number;
+    selection: number;
+    interaction: number;
+    /** `allocation + selection + interaction`. */
+    total: number;
+}
+type BrinsonMethod = 'brinson-fachler' | 'brinson-hood-beebower';
+/** Options for {@link brinsonAttribution}. */
+export interface BrinsonAttributionOptions {
+    /** Allocation convention; default `'brinson-fachler'` (benchmark-relative). */
+    method?: BrinsonMethod;
+}
+/** The Brinson attribution. */
+export interface BrinsonAttribution {
+    portfolioReturn: number;
+    benchmarkReturn: number;
+    /** `portfolioReturn − benchmarkReturn`. */
+    activeReturn: number;
+    /** Segment-summed effects (`allocation + selection + interaction = activeReturn`, exact). */
+    allocation: number;
+    selection: number;
+    interaction: number;
+    segments: SegmentEffect[];
+    method: BrinsonMethod;
+    assumptions: {
+        conventionsVersion: string;
+        method: BrinsonMethod;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Decompose a portfolio's active return vs a benchmark into allocation (sector bets), selection
+ * (security picks), and interaction — an exact decomposition (the three sum to the active return). See
+ * `docs/specs/attribution.md`.
+ */
+export declare function brinsonAttribution(segments: BrinsonSegment[], options?: BrinsonAttributionOptions): BrinsonAttribution;
+declare const LINK_METHODS: readonly ["carino"];
+type LinkMethod = (typeof LINK_METHODS)[number];
+/** One period's returns and Brinson effects, to be linked across time. */
+export interface AttributionPeriod {
+    portfolioReturn: number;
+    benchmarkReturn: number;
+    allocation: number;
+    selection: number;
+    interaction: number;
+    /** Optional per-segment effects (as from `brinsonAttribution().segments`) to link segment-by-segment. */
+    segments?: SegmentEffect[];
+    /** Optional period label, echoed onto its linking coefficient. */
+    label?: string;
+}
+/** Options for {@link linkAttribution}. */
+export interface LinkAttributionOptions {
+    /** Linking method; default (and currently only) `'carino'`. */
+    method?: LinkMethod;
+}
+/** A per-period Cariño linking coefficient `βₜ`. */
+export interface LinkingCoefficient {
+    label?: string;
+    coefficient: number;
+}
+/** The multi-period-linked attribution. */
+export interface LinkedAttribution {
+    /** Compounded portfolio return `∏(1+Pₜ) − 1`. */
+    portfolioReturn: number;
+    /** Compounded benchmark return `∏(1+Bₜ) − 1`. */
+    benchmarkReturn: number;
+    /** `portfolioReturn − benchmarkReturn` (the geometric active return). */
+    activeReturn: number;
+    /** Linked cumulative effects — `allocation + selection + interaction = activeReturn`, exact. */
+    allocation: number;
+    selection: number;
+    interaction: number;
+    /** The per-period linking coefficient `βₜ` (with the period `label` when supplied). */
+    linkingCoefficients: LinkingCoefficient[];
+    /** Linked per-segment effects — present only when every period supplied segments. */
+    segments?: SegmentEffect[];
+    method: LinkMethod;
+    assumptions: {
+        conventionsVersion: string;
+        method: LinkMethod;
+        periods: number;
+    };
+    diagnostics: Diagnostics;
+}
+/**
+ * Link single-period Brinson attributions across time with **Cariño's** logarithmic coefficients, so the
+ * cumulative allocation / selection / interaction sum **exactly** to the compounded (geometric) active
+ * return — the property the naive arithmetic sum lacks. Each period's effects are scaled by `βₜ = kₜ/k`;
+ * per-segment effects are linked with the same `βₜ`. See `docs/specs/attribution-linking.md`.
+ */
+export declare function linkAttribution(periods: AttributionPeriod[], options?: LinkAttributionOptions): LinkedAttribution;
+export {};
+//# sourceMappingURL=attribution.d.ts.map

package/modules/risk/dist/attribution.d.ts.map

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