@insiderfinance/totalfinance 0.1.0

package/modules/core/src/schema/standard.ts

@@ -0,0 +1,40 @@
+/**
+ * The Standard Schema v1 interface (https://standardschema.dev).
+ *
+ * TotalFinance schemas implement this so users can plug them into any Standard-Schema-aware tool
+ * (form libraries, RPC frameworks, etc.) without TotalFinance taking a dependency on a validator.
+ */
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1Props<Input, Output>;
+}
+
+export interface StandardSchemaV1Props<Input, Output> {
+  readonly version: 1;
+  readonly vendor: string;
+  readonly validate: (value: unknown) => StandardSchemaV1Result<Output>;
+  readonly types?: StandardSchemaV1Types<Input, Output> | undefined;
+}
+
+export type StandardSchemaV1Result<Output> =
+  | StandardSchemaV1SuccessResult<Output>
+  | StandardSchemaV1FailureResult;
+
+export interface StandardSchemaV1SuccessResult<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+
+export interface StandardSchemaV1FailureResult {
+  readonly issues: ReadonlyArray<StandardSchemaV1Issue>;
+}
+
+export interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey> | undefined;
+}
+
+export interface StandardSchemaV1Types<Input, Output> {
+  readonly input: Input;
+  readonly output: Output;
+}

package/modules/core/src/symbology.ts

@@ -0,0 +1,170 @@
+/**
+ * Option symbology (spec §7.7) — OCC / OPRA option symbols.
+ *
+ * OCC symbol layout (the "compact" OSI form): `<ROOT><YYMMDD><C|P><STRIKE×1000, 8 digits>`,
+ * e.g. `AAPL260918C00105000` = AAPL, 2026-09-18, call, strike 105.000. The fixed-width tail
+ * (6 date + 1 type + 8 strike = 15 chars) lets us parse regardless of root padding.
+ */
+
+import { ErrorCode, InputError } from './errors.js';
+import { requireArgumentObject } from './invariants.js';
+import { parseIsoDate } from './dates.js';
+import { resolvedExpiry } from './time.js';
+import type { OptionType } from './contracts.js';
+
+export interface OccOptionSymbol {
+  root: string;
+  /** ISO `YYYY-MM-DD`. */
+  expiry: string;
+  /** Resolved expiry instant (one expiry law, E2): OCC symbols are always US-equity date-only. */
+  expiresAt: number;
+  expiryConvention: 'us-equity-close';
+  type: OptionType;
+  strike: number;
+}
+
+const STRIKE_DIGITS = 8;
+const TAIL = 15; // YYMMDD(6) + C/P(1) + strike(8)
+
+/** The grammar of a compact OCC symbol, parsed and validated but not yet resolved to an instant. */
+interface OccSymbolParts {
+  root: string;
+  /** ISO `YYYY-MM-DD`. */
+  expiry: string;
+  type: OptionType;
+  strike: number;
+}
+
+/**
+ * The one OCC grammar: a fixed-width tail, `C`/`P`, an eight-digit strike in thousandths, a real
+ * calendar date, a non-empty root. Anything else throws a typed InputError. Kept apart from expiry
+ * resolution so a predicate can ask the grammar without bundling the session calendar.
+ */
+function occSymbolParts(symbol: string): OccSymbolParts {
+  const raw = symbol.trim();
+  if (raw.length < TAIL + 1) {
+    throw new InputError(`occSymbolParts: "${symbol}" is too short to be an OCC option symbol.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'occSymbol', value: symbol },
+    });
+  }
+
+  const strikeStr = raw.slice(-STRIKE_DIGITS);
+  const typeChar = raw.slice(-(STRIKE_DIGITS + 1), -STRIKE_DIGITS).toUpperCase();
+  const yymmdd = raw.slice(-TAIL, -(STRIKE_DIGITS + 1));
+  // Uppercase the root so parse/format round-trip symmetrically (format uppercases too).
+  const root = raw.slice(0, -TAIL).trim().toUpperCase();
+
+  if (
+    !/^\d{8}$/.test(strikeStr) ||
+    !/^\d{6}$/.test(yymmdd) ||
+    (typeChar !== 'C' && typeChar !== 'P')
+  ) {
+    throw new InputError(`occSymbolParts: "${symbol}" is not a valid OCC option symbol.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'occSymbol', value: symbol },
+    });
+  }
+  if (root.length === 0) {
+    throw new InputError(`occSymbolParts: "${symbol}" is missing a root symbol.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'root', value: symbol },
+    });
+  }
+
+  const expiry = `20${yymmdd.slice(0, 2)}-${yymmdd.slice(2, 4)}-${yymmdd.slice(4, 6)}`;
+  parseIsoDate(expiry); // reject impossible dates like 2099-13-32 (throws InputOutOfRange)
+  const strike = Number(strikeStr) / 1000;
+  // A `00000000` strike is not a contract: no listed option has strike 0, and the parse result
+  // could never round-trip (formatOccSymbol rejects strike <= 0 with this same message).
+  if (!(strike > 0)) {
+    throw new InputError(`occSymbolParts: Strike must be > 0, received ${strike}.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { field: 'strike', value: strike },
+    });
+  }
+
+  return { root, expiry, type: typeChar === 'C' ? 'call' : 'put', strike };
+}
+
+/** Parse an OCC option symbol into its components. */
+export function parseOccSymbol(symbol: string): OccOptionSymbol {
+  const { root, expiry, type, strike } = occSymbolParts(symbol);
+  return {
+    root,
+    expiry,
+    ...(resolvedExpiry(expiry) as { expiresAt: number; expiryConvention: 'us-equity-close' }),
+    type,
+    strike,
+  };
+}
+
+/**
+ * Whether `symbol` is an OCC option symbol: true exactly when the OCC grammar accepts it — the
+ * same parse {@link parseOccSymbol} performs before resolving the expiry instant. The grammar lives
+ * in one place; this only asks the question, so a broker or a plan can refuse to treat an option
+ * contract as a share without re-describing the symbol layout or bundling the session calendar.
+ */
+export function isOccOptionSymbol(symbol: string): boolean {
+  if (typeof symbol !== 'string') {
+    throw new InputError(
+      `isOccOptionSymbol: symbol must be a string. Received ${symbol === null ? 'null' : typeof symbol}.`,
+      { code: ErrorCode.InputWrongType, context: { field: 'symbol' } },
+    );
+  }
+  try {
+    occSymbolParts(symbol);
+    return true;
+  } catch (error) {
+    if (error instanceof InputError) return false;
+    throw error;
+  }
+}
+
+/** Format option components into a compact OCC option symbol. */
+export function formatOccSymbol(
+  // Formatting needs only the four symbol components — parse output (which also carries the
+  // resolved expiry instant) still round-trips, and format callers need not resolve first.
+  option: Pick<OccOptionSymbol, 'root' | 'expiry' | 'type' | 'strike'>,
+): string {
+  requireArgumentObject('formatOccSymbol', 'option', option);
+  // NO key closure, deliberately: parse output (which also carries `expiresAt`) round-trips
+  // through format by documented contract — the option is a decorated parse artifact.
+  if (typeof option.root !== 'string' || option.root.length === 0) {
+    throw new InputError(
+      `formatOccSymbol: root must be a non-empty underlying root — formatOccSymbol({ root: 'AAPL', expiry: '2026-06-19', type: 'call', strike: 210 }). Received ${option.root === null ? 'null' : option.root === undefined ? 'undefined' : typeof option.root}.`,
+      { code: ErrorCode.InputWrongType, context: { field: 'root' } },
+    );
+  }
+  // Validate the real calendar date (not just the shape) so we never emit a garbage symbol.
+  const { year, month, day } = parseIsoDate(option.expiry);
+  if (!(option.strike > 0)) {
+    throw new InputError(`formatOccSymbol: Strike must be > 0, received ${option.strike}.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { field: 'strike', value: option.strike },
+    });
+  }
+
+  const yy = String(year).slice(2);
+  const date = `${yy}${String(month).padStart(2, '0')}${String(day).padStart(2, '0')}`;
+  // Option type changes the meaning of the whole symbol — never coerce 'CALL'/'C'/typos to a put.
+  if (option.type !== 'call' && option.type !== 'put') {
+    throw new InputError(
+      `formatOccSymbol: type must be 'call' or 'put' (lowercase). Received ${JSON.stringify(option.type)}.`,
+      { code: ErrorCode.InputInvalidEnum, context: { field: 'type', value: option.type } },
+    );
+  }
+  const typeChar = option.type === 'call' ? 'C' : 'P';
+  const strikeThousandths = Math.round(option.strike * 1000);
+  const strikeStr = String(strikeThousandths).padStart(STRIKE_DIGITS, '0');
+  if (strikeStr.length > STRIKE_DIGITS) {
+    throw new InputError(
+      `formatOccSymbol: Strike ${option.strike} is too large for an OCC symbol.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { field: 'strike', value: option.strike },
+      },
+    );
+  }
+  return `${option.root.trim().toUpperCase()}${date}${typeChar}${strikeStr}`;
+}

package/modules/core/src/time.ts

@@ -0,0 +1,458 @@
+/**
+ * Time primitives (spec §7.2).
+ *
+ * The internal contract is Unix epoch milliseconds. Core calculations NEVER read the system clock;
+ * `asOf` is always injected by the caller (design law #5).
+ */
+
+import {
+  type HolidayRule,
+  addDays,
+  dayOfWeek,
+  nthWeekdayOfMonth,
+  observedHoliday,
+  ymd,
+} from './calendar.js';
+import { isoDateToEpochMs, parseIsoDate } from './dates.js';
+import { ErrorCode, InputError, UnsupportedError } from './errors.js';
+
+/** Unix epoch milliseconds. */
+export type EpochMs = number;
+
+/** Day-count conventions supported in the 0.0.1 surface. */
+export type DayCount = 'ACT/365F' | 'ACT/360' | '30/360';
+
+/** Interest compounding conventions. */
+/**
+ * The ONE public interest-compounding grammar (FC0). Every rate-bearing contract in the library
+ * quotes its compounding in this vocabulary — the former core `'continuous' | 'simple'` pair and
+ * fixed-income's separate curve grammar (with its bare-number periodic form) are unified here,
+ * with no compatibility aliases (pre-1.0). The object form names its meaning: a bare `12` said
+ * nothing about being periods-per-year.
+ */
+export type InterestCompounding =
+  | 'simple'
+  | 'continuous'
+  | 'annual'
+  | 'semiannual'
+  | 'quarterly'
+  | 'monthly'
+  | { type: 'periodic'; periodsPerYear: number };
+
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * The America/New_York UTC offset (minutes east of UTC) in force at a given UTC wall-clock probe —
+ * DST-aware via `Intl`. Throws rather than silently assuming EST (wrong by an hour half the year).
+ */
+function newYorkOffsetMinutes(
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  functionName: string,
+): number {
+  const tzName = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'America/New_York',
+    timeZoneName: 'longOffset',
+  })
+    .formatToParts(new Date(Date.UTC(year, month - 1, day, hour)))
+    .find((p) => p.type === 'timeZoneName')?.value;
+  const m = tzName?.match(/GMT([+-])(\d{1,2})(?::?(\d{2}))?/);
+  if (!m) {
+    throw new UnsupportedError(
+      `${functionName}: could not resolve the America/New_York UTC offset from Intl (got "${tzName}").`,
+      { code: ErrorCode.TimeTimezoneResolutionFailed, context: { year, month, day, tzName } },
+    );
+  }
+  return (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3] ?? 0));
+}
+
+/** `"-04:00"` / `"-05:00"`: the New York offset label for a calendar date, for teaching examples. */
+function newYorkOffsetLabel(year: number, month: number, day: number): string {
+  const minutes = newYorkOffsetMinutes(year, month, day, 12, 'newYorkOffsetLabel');
+  const sign = minutes < 0 ? '-' : '+';
+  const abs = Math.abs(minutes);
+  return `${sign}${String(Math.floor(abs / 60)).padStart(2, '0')}:${String(abs % 60).padStart(2, '0')}`;
+}
+
+/**
+ * US equity/options early-close (13:00 ET) rules — the ONE table, consumed by `@insiderfinance/totalfinance/calendars`
+ * as well: the day after Thanksgiving, and 24 December and 3 July when they fall on a weekday and
+ * are not themselves the observed Christmas / Independence Day holiday. A rule returns the
+ * candidate date for a year; {@link isUsEquityHalfDay} applies the weekday/observance exclusions.
+ */
+export const US_EQUITY_HALF_DAY_RULES: readonly HolidayRule[] = [
+  // Day after Thanksgiving. Every November has a 4th Thursday, so the generator's "no such
+  // occurrence" channel never fires here — propagate it rather than assert it away.
+  (y) => {
+    const thanksgiving = nthWeekdayOfMonth(y, 11, 4, 4);
+    return thanksgiving === null ? null : addDays(thanksgiving, 1);
+  },
+  (y) => `${y}-12-24`, // Christmas Eve (a weekend or the observed Christmas holiday is not a half day)
+  (y) => `${y}-07-03`, // 3 July (a weekend or the observed Independence Day holiday is not a half day)
+];
+
+/**
+ * Whether a `YYYY-MM-DD` calendar date is a US equity/options early-close day (13:00 ET). Applies
+ * {@link US_EQUITY_HALF_DAY_RULES} with the weekend and observed-holiday exclusions, so
+ * 2021-12-24 (the observed Christmas holiday) and 2026-07-03 (the observed Independence Day
+ * holiday) are full closures, not half days.
+ */
+export function isUsEquityHalfDay(date: string): boolean {
+  const { year, month, day } = parseIsoDate(date);
+  const label = ymd(year, month, day);
+  const dow = dayOfWeek(label);
+  if (dow === 0 || dow === 6) return false;
+  if (observedHoliday(year, 12, 25) === label || observedHoliday(year, 7, 4) === label)
+    return false;
+  return US_EQUITY_HALF_DAY_RULES.some((rule) => rule(year) === label);
+}
+
+/**
+ * UTC epoch-ms for the **US equity/options market close** on a calendar date — 16:00
+ * America/New_York, or 13:00 on an early-close day ({@link isUsEquityHalfDay}) — DST-aware via
+ * `Intl`. Use it to resolve a *date-only* option expiry to its end-of-session instant instead of
+ * UTC midnight, so a contract stays alive through its expiry trading day. This encodes US-equity
+ * hours specifically; it is not a generic exchange close.
+ */
+export function usEquityCloseUtcMs(year: number, month: number, day: number): EpochMs {
+  const hour = isUsEquityHalfDay(ymd(year, month, day)) ? 13 : 16;
+  const offsetMinutes = newYorkOffsetMinutes(year, month, day, hour, 'usEquityCloseUtcMs');
+  // `hour`:00 on the local ET clock, expressed in UTC, is `Date.UTC(..., hour) − offset`.
+  return Date.UTC(year, month - 1, day, hour, 0, 0) - offsetMinutes * 60_000;
+}
+
+/**
+ * UTC epoch-ms for the **US equity/options market open** (09:30 America/New_York) on a calendar
+ * date — DST-aware via `Intl`. The session open is the same on early-close days.
+ */
+function usEquityOpenUtcMs(year: number, month: number, day: number): EpochMs {
+  const offsetMinutes = newYorkOffsetMinutes(year, month, day, 9, 'usEquityOpenUtcMs');
+  return Date.UTC(year, month - 1, day, 9, 30, 0) - offsetMinutes * 60_000;
+}
+
+/**
+ * The instant of a US equity/options session boundary on a `YYYY-MM-DD` date — the one-call way
+ * to say "as of today's close" without remembering the DST offset:
+ *
+ * ```ts
+ * market({ spot: 195.3, riskFreeRate: 0.045, volatility: 0.24, asOf: usEquitySessionInstant('2026-07-20', 'close') })
+ * ```
+ *
+ * `'open'` is 09:30 ET; `'close'` is 16:00 ET, or 13:00 ET on an early-close day. Weekends and
+ * holidays are not rejected here (the instant still exists); use `@insiderfinance/totalfinance/calendars` to ask
+ * whether the market was open.
+ */
+export function usEquitySessionInstant(date: string, session: 'open' | 'close'): EpochMs {
+  const functionName = 'usEquitySessionInstant';
+  if (typeof date !== 'string' || !DATE_ONLY.test(date)) {
+    throw new InputError(
+      `${functionName}: date must be a YYYY-MM-DD calendar date (e.g. '2026-07-20'). Received ${
+        typeof date === 'string' ? `"${date}"` : date === null ? 'null' : typeof date
+      }.`,
+      { code: ErrorCode.InputWrongType, context: { function: functionName, field: 'date', date } },
+    );
+  }
+  if (session !== 'open' && session !== 'close') {
+    throw new InputError(
+      `${functionName}: session must be 'open' (09:30 ET) or 'close' (16:00 ET, 13:00 on early-close days). Received ${
+        typeof session === 'string' ? `"${session}"` : session === null ? 'null' : typeof session
+      }.`,
+      {
+        code: ErrorCode.InputInvalidEnum,
+        context: { function: functionName, field: 'session', session },
+      },
+    );
+  }
+  const { year, month, day } = parseIsoDate(date);
+  return session === 'open'
+    ? usEquityOpenUtcMs(year, month, day)
+    : usEquityCloseUtcMs(year, month, day);
+}
+
+/**
+ * `Intl.DateTimeFormat` is expensive to construct and the market-day index runs per contract per
+ * level — build the formatter once. Numbering system pinned to `latn` so a host default of e.g.
+ * `arab` digits cannot turn the parse into `NaN`.
+ */
+const NEW_YORK_DATE_PARTS = new Intl.DateTimeFormat('en-US-u-ca-gregory-nu-latn', {
+  timeZone: 'America/New_York',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  era: 'short',
+});
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * The US equity/options market's calendar DAY an instant falls on, as a whole-day index (days since
+ * the epoch of the America/New_York calendar date). Differencing two indices gives whole CALENDAR
+ * DAYS between two market dates; equality means "same trading date". This is the ONE day boundary
+ * shared by 0DTE classification, days-to-expiry counts and earnings day counts: expiries resolve to
+ * 16:00 ET (20:00/21:00 UTC), so a UTC-day comparison is already "tomorrow" between 20:00 and
+ * 23:59 ET. Pure and clock-free.
+ */
+export function usEquityMarketDayIndex(epochMs: EpochMs): number {
+  const parts = NEW_YORK_DATE_PARTS.formatToParts(new Date(epochMs));
+  let year = NaN;
+  let month = NaN;
+  let day = NaN;
+  let bc = false;
+  for (const part of parts) {
+    if (part.type === 'year') year = Number(part.value);
+    else if (part.type === 'month') month = Number(part.value);
+    else if (part.type === 'day') day = Number(part.value);
+    else if (part.type === 'era') bc = part.value.startsWith('B');
+  }
+  // Date.UTC of the LOCAL Y/M/D — a pure re-encoding of the calendar date, never a re-zoning.
+  return Math.round(Date.UTC(bc ? 1 - year : year, month - 1, day) / MS_PER_DAY);
+}
+
+/**
+ * UTC-midnight epoch of the market DATE an instant falls on — the anchor for weekday / day-of-month
+ * arithmetic (`getUTCDay()` on it is the ET weekday) and for whole-day counts against date labels.
+ */
+export function usEquityMarketDateUtcMs(epochMs: EpochMs): EpochMs {
+  return usEquityMarketDayIndex(epochMs) * MS_PER_DAY;
+}
+
+/**
+ * Parse an option-expiry label to epoch-ms. A bare `YYYY-MM-DD` resolves to {@link usEquityCloseUtcMs}
+ * (16:00 ET) — not UTC midnight — so an intraday `asOf` on the expiry date still sees positive
+ * time-to-expiry; a full datetime string is parsed as-is. Throws on an unparseable value.
+ */
+export function optionExpiryToMs(expiry: string): EpochMs {
+  if (DATE_ONLY.test(expiry)) {
+    // Validate it is a real calendar date — `parseIsoDate` rejects e.g. 2026-02-31 rather than letting
+    // Date.UTC silently roll it forward to 2026-03-03.
+    const { year, month, day } = parseIsoDate(expiry);
+    return usEquityCloseUtcMs(year, month, day);
+  }
+  // Full datetimes must carry an explicit zone (Z or ±HH:MM). A bare '2026-09-18T16:00' would parse
+  // in the MACHINE's local zone — the same input yielding different epochs on different boxes breaks
+  // the determinism law (design law #5) — so it is rejected with the fix, never silently localized.
+  if (DATETIME_ZONED.test(expiry))
+    return parseZonedDatetimeMs(expiry, 'optionExpiryToMs', 'expiry');
+  if (DATETIME_BARE.test(expiry)) {
+    throw new InputError(
+      `optionExpiryToMs: datetime expiry "${expiry}" has no timezone — append 'Z' or an offset like '-05:00' (a bare datetime would silently parse in the machine's local zone).`,
+      { code: ErrorCode.InputWrongType, context: { expiry } },
+    );
+  }
+  throw new InputError(
+    `optionExpiryToMs: cannot parse expiry "${expiry}" — use 'YYYY-MM-DD' (resolves to 16:00 ET) or a zoned ISO datetime.`,
+    { code: ErrorCode.InputWrongType, context: { expiry } },
+  );
+}
+
+// `[Tt ]` and `[Zz]`: RFC 3339 explicitly permits the lowercase date/time separator and zone
+// designator, so `2026-07-06t12:00:00z` is the same legal instant as its uppercase form.
+// Everything else stays strict.
+const DATETIME_ZONED =
+  /^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?([Zz]|[+-]\d{2}:?\d{2})$/;
+const DATETIME_BARE = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}/;
+
+/**
+ * STRICT zoned-datetime parsing (D2, one expiry law): every component is range-checked and the
+ * epoch is computed arithmetically — `Date.parse` is never trusted. Without this,
+ * `2026-02-31T16:00:00Z` silently normalizes into March and `T25:00` yields NaN, both of which
+ * would flow into "valid by construction" frozen contracts.
+ */
+function parseZonedDatetimeMs(value: string, functionName: string, field: string): EpochMs {
+  const m = DATETIME_ZONED.exec(value);
+  if (!m) {
+    throw new InputError(`${functionName}: ${field} "${value}" is not a zoned ISO datetime.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field, value },
+    });
+  }
+  const [, ys, mos, ds, hs, mins, secs, frac, zone] = m;
+  // Real calendar date (rejects 2026-02-31 / month 13 instead of rolling forward). Built via
+  // setUTCFullYear so years 0000–0099 stay literal — Date.UTC would remap them to 1900–1999.
+  const probe = new Date(0);
+  probe.setUTCFullYear(Number(ys), Number(mos) - 1, Number(ds));
+  const validDate =
+    probe.getUTCFullYear() === Number(ys) &&
+    probe.getUTCMonth() === Number(mos) - 1 &&
+    probe.getUTCDate() === Number(ds);
+  const hour = Number(hs);
+  const minute = Number(mins);
+  const second = secs === undefined ? 0 : Number(secs);
+  let offsetMinutes = 0;
+  let validZone = true;
+  if (zone !== 'Z' && zone !== 'z' && zone !== undefined) {
+    const zm = /^([+-])(\d{2}):?(\d{2})$/.exec(zone);
+    if (!zm) validZone = false;
+    else {
+      const oh = Number(zm[2]);
+      const om = Number(zm[3]);
+      // RFC 3339 real-world envelope: offsets run −12:00 … +14:00 EXACTLY — +14:59 is not a
+      // real place (the error contract promises this bound, so the code enforces it).
+      validZone =
+        om <= 59 &&
+        (zm[1] === '+' ? oh < 14 || (oh === 14 && om === 0) : oh < 12 || (oh === 12 && om === 0));
+      offsetMinutes = (zm[1] === '-' ? -1 : 1) * (oh * 60 + om);
+    }
+  }
+  if (!validDate || hour > 23 || minute > 59 || second > 59 || !validZone) {
+    throw new InputError(
+      `${functionName}: ${field} "${value}" is not a valid instant — ` +
+        (!validDate
+          ? 'the calendar date does not exist'
+          : !validZone
+            ? 'the UTC offset is out of range (−12:00 … +14:00)'
+            : 'the time-of-day component is out of range') +
+        ' (components are verified exactly; nothing is silently normalized).',
+      { code: ErrorCode.InputOutOfRange, context: { field, value } },
+    );
+  }
+  const fracMs = frac === undefined ? 0 : Math.round(Number(frac) * 1000);
+  // Time-of-day arithmetic on the validated midnight probe (not Date.UTC, which would remap
+  // years 0000–0099): midnight epoch + h/m/s/frac − zone offset.
+  return (
+    probe.getTime() + ((hour * 60 + minute) * 60 + second) * 1000 + fracMs - offsetMinutes * 60_000
+  );
+}
+
+/**
+ * Resolve a DATE-GRANULAR `asOf` to epoch ms — ledgers, calendars, fundamentals, performance and
+ * research windows, where "as of 2026-07-06" means the calendar date. Deterministic by
+ * construction: bare dates resolve to UTC midnight, datetimes require an explicit zone, and
+ * anything else throws a teaching error (never a machine-local parse).
+ *
+ * Option-pricing paths must NOT use this door: a bare date hides the time of day that a same-day
+ * option's value depends on. They resolve through {@link resolveValuationAsOf}, which rejects a
+ * date-only `asOf` with the fix.
+ */
+export function resolveAsOf(asOf: EpochMs | string, functionName = 'resolveAsOf'): EpochMs {
+  if (typeof asOf === 'number') {
+    // The numeric branch obeys the first-touch law too: NaN/Infinity here would flow downstream
+    // as a poisoned timestamp and surface far from the mistake.
+    if (!Number.isFinite(asOf)) {
+      throw new InputError(
+        `${functionName}: asOf must be finite epoch milliseconds. Received ${asOf}. TotalFinance never reads the system clock — pass the current instant from your own clock (epoch milliseconds or a zoned ISO datetime).`,
+        { code: ErrorCode.InputNotFinite, context: { asOf } },
+      );
+    }
+    return asOf;
+  }
+  if (typeof asOf === 'string') {
+    if (DATE_ONLY.test(asOf)) {
+      // Validates the calendar date AND keeps years 0000–0099 literal (isoDateToEpochMs builds the
+      // epoch via setUTCFullYear; a direct Date.UTC would remap those years to 1900–1999).
+      return isoDateToEpochMs(asOf);
+    }
+    if (DATETIME_ZONED.test(asOf)) return parseZonedDatetimeMs(asOf, functionName, 'asOf');
+    if (DATETIME_BARE.test(asOf)) {
+      throw new InputError(
+        `${functionName}: asOf datetime "${asOf}" has no timezone — append 'Z' or an offset like '-05:00' (a bare datetime would silently parse in the machine's local zone).`,
+        { code: ErrorCode.InputWrongType, context: { asOf } },
+      );
+    }
+    throw new InputError(
+      `${functionName}: cannot parse asOf "${asOf}" — use epoch milliseconds, 'YYYY-MM-DD', or a zoned ISO datetime.`,
+      { code: ErrorCode.InputWrongType, context: { asOf } },
+    );
+  }
+  throw new InputError(
+    `${functionName}: asOf must be epoch milliseconds or an ISO date string. Received ${asOf === null ? 'null' : typeof asOf}.`,
+    { code: ErrorCode.InputWrongType, context: { asOf } },
+  );
+}
+
+/**
+ * Resolve a VALUATION instant (`asOf`) to epoch ms — the door every option-pricing path uses
+ * (options, strategy, volatility, structure, scenarios, risk marking). Accepts finite epoch
+ * milliseconds or a zoned ISO datetime. A date-only string is REJECTED with the fix: the time of
+ * day is the whole answer for a same-day option (a bare date resolved to UTC midnight valued a
+ * 0DTE at 10:30 ET with 3.6× its remaining life), and the expiry side already refuses a bare date
+ * that does not name its instant. `usEquitySessionInstant(date, 'close')` is the one-call form
+ * for an end-of-day mark.
+ */
+export function resolveValuationAsOf(
+  asOf: EpochMs | string,
+  functionName = 'resolveValuationAsOf',
+): EpochMs {
+  if (typeof asOf === 'string' && DATE_ONLY.test(asOf)) {
+    // Validate the calendar date first so an impossible date teaches THAT, not the instant rule.
+    const { year, month, day } = parseIsoDate(asOf);
+    const offset = newYorkOffsetLabel(year, month, day);
+    throw new InputError(
+      `${functionName}: asOf "${asOf}" is a date with no time of day, and a valuation instant needs one — a same-day option's value depends on it. Pass a zoned datetime like "${asOf}T10:30:00${offset}", epoch milliseconds, or usEquitySessionInstant('${asOf}', 'close') for that day's US market close.`,
+      {
+        code: ErrorCode.TimeValuationInstantRequired,
+        context: { function: functionName, field: 'asOf', asOf },
+      },
+    );
+  }
+  return resolveAsOf(asOf, functionName);
+}
+
+/**
+ * ONE expiry law, cross-field (E2): validate that a resolved option-expiry triple —
+ * `expiry` label, `expiresAt` instant, `expiryConvention` — is internally consistent:
+ *
+ *   - the label parses, and its form matches the convention (date-only ⇔ `us-equity-close`,
+ *     zoned datetime ⇔ `explicit-instant`);
+ *   - `expiresAt` is the finite instant the label resolves to under that convention.
+ *
+ * Shared by the contract schema and the pro pricing entrypoints, so a hand-assembled or
+ * post-hoc-edited contract can never smuggle a contradictory resolution past an engine.
+ */
+export function validateResolvedExpiry(
+  functionName: string,
+  expiry: string,
+  expiresAt: unknown,
+  expiryConvention: unknown,
+): void {
+  if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) {
+    throw new InputError(
+      `${functionName}: contract.expiresAt must be a finite epoch-ms instant (got ${String(expiresAt)}). ` +
+        'Build contracts with the option builders — a raw literal is not a resolved contract.',
+      { code: ErrorCode.InputMissingField, context: { function: functionName, expiresAt } },
+    );
+  }
+  const isDateOnly = typeof expiry === 'string' && DATE_ONLY.test(expiry);
+  const expected = isDateOnly ? 'us-equity-close' : 'explicit-instant';
+  if (expiryConvention !== expected) {
+    throw new InputError(
+      `${functionName}: expiryConvention "${String(expiryConvention)}" contradicts the expiry label ` +
+        `"${expiry}" (${isDateOnly ? 'a date-only label resolves via' : 'a zoned instant is'} ` +
+        `'${expected}').`,
+      {
+        code: ErrorCode.InputWrongShape,
+        context: { function: functionName, expiry, expiryConvention },
+      },
+    );
+  }
+  const fromLabel = optionExpiryToMs(expiry);
+  if (fromLabel !== expiresAt) {
+    throw new InputError(
+      `${functionName}: contract.expiry "${expiry}" resolves to ${fromLabel} but contract.expiresAt is ` +
+        `${expiresAt} — the contract was mutated after construction. Rebuild it with the option ` +
+        'builders instead of editing fields.',
+      {
+        code: ErrorCode.InputWrongShape,
+        context: { function: functionName, expiry, expiresAt, fromLabel },
+      },
+    );
+  }
+}
+
+/**
+ * Resolve an expiry label to the REQUIRED contract fields (E2): the spreadable
+ * `{ expiresAt, expiryConvention }` pair for constructing an `OptionContract` from a label —
+ * the same resolution the option builders stamp. Prefer the builders for user-facing code;
+ * this exists for adapters and tests assembling contracts inline.
+ */
+export function resolvedExpiry(expiry: string): {
+  expiresAt: EpochMs;
+  expiryConvention: 'us-equity-close' | 'explicit-instant';
+} {
+  return {
+    expiresAt: optionExpiryToMs(expiry),
+    expiryConvention: DATE_ONLY.test(expiry) ? 'us-equity-close' : 'explicit-instant',
+  };
+}