@insiderfinance/totalfinance 0.1.0

package/modules/core/dist/artifacts/table-handle.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The large-table reference (Gate B): a saved artifact NAMES its big tabular outputs instead of
+ * inlining them, so envelopes stay small enough to hash, diff, store, and hand to an agent —
+ * roadmap Journey 3's "no large chain must travel through an LLM context", made structural.
+ *
+ * A handle is identity + dimensions + an OPAQUE locator. The spine deliberately owns no storage:
+ * `locator` is whatever string the caller's storage layer understands (a path, URL, cache key),
+ * and the `contentHash` is what makes the reference verifiable wherever the bytes actually live —
+ * fetch the table, hash its canonical JSON row projection, compare.
+ *
+ * `mediaType` is `application/json` today. A lossless Arrow mapping is RESERVED, not implemented:
+ * the contract is that an Arrow-encoded table hashes over the SAME canonical JSON row projection,
+ * so one logical table has one identity in either encoding. Implementation waits for a measured
+ * large-table consumer — performance work is explicitly deferred in this repo by user decision.
+ */
+export declare const TABLE_HANDLE_KIND = "totalfinance.table-handle";
+/** The reserved (unimplemented) Arrow media type — reserved here so no caller invents a second name. */
+export declare const TABLE_MEDIA_TYPE_ARROW_RESERVED = "application/vnd.apache.arrow.file";
+export interface TableHandle {
+    kind: typeof TABLE_HANDLE_KIND;
+    /** `sha256:` hash of the table's canonical JSON row projection — encoding-independent identity. */
+    contentHash: string;
+    rowCount: number;
+    columnCount: number;
+    /** Column names, in table order; when present, `columns.length === columnCount`. */
+    columns?: string[];
+    /** Storage-agnostic opaque reference — meaningful only to the storage layer that minted it. */
+    locator?: string;
+    /** Concrete encoding of the stored bytes. `application/json` unless a future Arrow mapping lands. */
+    mediaType?: string;
+}
+/**
+ * The FULL table-handle validator, shared by `createTableHandle`, every envelope site that accepts
+ * a stored handle (artifact `tables`, snapshot chain `table`), AND the public {@link isTableHandle}
+ * guard — one validator, so a handle that would be refused at creation can never slip into an
+ * envelope pre-built or pass the guard. Beyond kind/hash/counts it enforces the optional-field
+ * contracts: `columns` an array of non-empty, DUPLICATE-FREE column-name strings whose length
+ * equals `columnCount`, `locator` a non-empty string when present, and `mediaType` a non-empty
+ * media-type string when present. Returns the (unchanged) validated handle.
+ */
+export declare function requireTableHandle(functionName: string, label: string, value: unknown): TableHandle;
+/**
+ * Structural PREDICATE for a table handle: the COMPLETE {@link requireTableHandle} validation
+ * behind a boolean door, so `value is TableHandle` is a sound claim — `true` means every envelope
+ * site would accept the handle unchanged. (An earlier version checked only the required fields, so
+ * `{ …, columns: 42 }` passed the guard and then detonated at the first validation site; a guard
+ * that is a weaker law than the validator is a `false` dressed as a `true`.) It runs the full
+ * field walk — not a constant-time tag sniff — which for a handle (a dozen scalar fields) is still
+ * trivially cheap.
+ */
+export declare function isTableHandle(value: unknown): value is TableHandle;
+/**
+ * Build a validated, frozen table handle.
+ *
+ * @example
+ * ```ts
+ * const handle = createTableHandle({
+ *   contentHash: contentHash(chainRows),
+ *   rowCount: chainRows.length,
+ *   columnCount: 8,
+ *   columns: ['strike', 'expiry', 'bid', 'ask', 'mid', 'volume', 'openInterest', 'impliedVolatility'],
+ *   locator: 'artifacts/chains/aapl-2026-07-20.json',
+ * });
+ * ```
+ */
+export declare function createTableHandle(input: {
+    contentHash: string;
+    rowCount: number;
+    columnCount: number;
+    columns?: string[];
+    locator?: string;
+    mediaType?: string;
+}): TableHandle;
+/**
+ * Mint the table handle for a row set the caller holds (Stage 4.5 Decision 4 — the ONE column law
+ * every package shares, so the same rows always mint the same handle):
+ *
+ * - an array of plain records → `columns` is the sorted union of the rows' own keys;
+ * - an array of numbers (a returns or realized-variance vector) → one column, `['value']`;
+ * - anything else (mixed rows, nested arrays, non-plain objects) is refused with the teaching.
+ *
+ * `contentHash` is the canonical-JSON hash of the rows exactly as given, so a consumer that later
+ * receives rows can prove they are the referenced ones by re-minting and comparing hashes.
+ *
+ * @example
+ * ```ts
+ * const handle = tableHandleForRows({ rows: observations, locator: 'universe/2026-09-01.json' });
+ * // { kind: 'totalfinance.table-handle', contentHash: 'sha256:…', rowCount: 4200, columnCount: 3, columns: ['availableTimestampMs', 'fields', 'instrumentId'] }
+ * ```
+ */
+export declare function tableHandleForRows(input: {
+    rows: readonly unknown[];
+    locator?: string;
+    mediaType?: string;
+}): TableHandle;
+//# sourceMappingURL=table-handle.d.ts.map

package/modules/core/dist/artifacts/table-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-handle.d.ts","sourceRoot":"","sources":["../../src/artifacts/table-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,wGAAwG;AACxG,eAAO,MAAM,+BAA+B,sCAAsC,CAAC;AAEnF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,iBAAiB,CAAC;IAC/B,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,GACb,WAAW,CA+Fb;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAgCd;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CAuDd"}

package/modules/core/dist/artifacts/table-handle.js

@@ -0,0 +1,253 @@
+/**
+ * The large-table reference (Gate B): a saved artifact NAMES its big tabular outputs instead of
+ * inlining them, so envelopes stay small enough to hash, diff, store, and hand to an agent —
+ * roadmap Journey 3's "no large chain must travel through an LLM context", made structural.
+ *
+ * A handle is identity + dimensions + an OPAQUE locator. The spine deliberately owns no storage:
+ * `locator` is whatever string the caller's storage layer understands (a path, URL, cache key),
+ * and the `contentHash` is what makes the reference verifiable wherever the bytes actually live —
+ * fetch the table, hash its canonical JSON row projection, compare.
+ *
+ * `mediaType` is `application/json` today. A lossless Arrow mapping is RESERVED, not implemented:
+ * the contract is that an Arrow-encoded table hashes over the SAME canonical JSON row projection,
+ * so one logical table has one identity in either encoding. Implementation waits for a measured
+ * large-table consumer — performance work is explicitly deferred in this repo by user decision.
+ */
+import { ErrorCode, InputError } from '../errors.js';
+import { ensureKnownKeys, requireArgumentObject } from '../invariants.js';
+import { contentHash, isContentHashString } from './content-hash.js';
+import { scanCanonicalData } from './canonical-scan.js';
+export const TABLE_HANDLE_KIND = 'totalfinance.table-handle';
+/** The reserved (unimplemented) Arrow media type — reserved here so no caller invents a second name. */
+export const TABLE_MEDIA_TYPE_ARROW_RESERVED = 'application/vnd.apache.arrow.file';
+const TABLE_HANDLE_KEYS = [
+    'kind',
+    'contentHash',
+    'rowCount',
+    'columnCount',
+    'columns',
+    'locator',
+    'mediaType',
+];
+/**
+ * Row/column counts are METADATA — they drive no loop or allocation here, so they take no
+ * practical cap — but they must be SAFE integers (2026-08-23 review, P0 "unbounded work"
+ * wave): `Number.isInteger(1e308)` is `true`, yet above 2^53 an IEEE-754 double skips integers,
+ * so such a "count" can neither be exact nor honestly compared against the table it names.
+ */
+function requireCount(functionName, field, value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new InputError(`${functionName}: ${field} must be a non-negative safe integer (≤ 2^53 − 1 = 9,007,199,254,740,991 — above that, doubles skip integers and a count stops being exact). Received ${typeof value === 'number' ? value : value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputOutOfRange, context: { function: functionName, field } });
+    }
+    return value;
+}
+/**
+ * The FULL table-handle validator, shared by `createTableHandle`, every envelope site that accepts
+ * a stored handle (artifact `tables`, snapshot chain `table`), AND the public {@link isTableHandle}
+ * guard — one validator, so a handle that would be refused at creation can never slip into an
+ * envelope pre-built or pass the guard. Beyond kind/hash/counts it enforces the optional-field
+ * contracts: `columns` an array of non-empty, DUPLICATE-FREE column-name strings whose length
+ * equals `columnCount`, `locator` a non-empty string when present, and `mediaType` a non-empty
+ * media-type string when present. Returns the (unchanged) validated handle.
+ */
+export function requireTableHandle(functionName, label, value) {
+    requireArgumentObject(functionName, label, value);
+    const handle = value;
+    ensureKnownKeys(functionName, label, handle, TABLE_HANDLE_KEYS);
+    if (handle.kind !== TABLE_HANDLE_KIND) {
+        throw new InputError(`${functionName}: ${label}.kind must be '${TABLE_HANDLE_KIND}'. Received ${JSON.stringify(handle.kind)} — build handles with createTableHandle({ contentHash, rowCount, columnCount, … }).`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${label}.kind` },
+        });
+    }
+    const suppliedHash = handle.contentHash;
+    if (!isContentHashString(suppliedHash)) {
+        throw new InputError(`${functionName}: ${label}.contentHash must be a 'sha256:<64 hex>' string — build it with contentHash(rows). ` +
+            `Received ${typeof suppliedHash === 'string' ? `"${suppliedHash.slice(0, 24)}…"` : suppliedHash === null ? 'null' : typeof suppliedHash}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${label}.contentHash` },
+        });
+    }
+    requireCount(functionName, `${label}.rowCount`, handle.rowCount);
+    const columnCount = requireCount(functionName, `${label}.columnCount`, handle.columnCount);
+    if (handle.columns !== undefined) {
+        if (!Array.isArray(handle.columns) ||
+            handle.columns.some((c) => typeof c !== 'string' || c.length === 0)) {
+            throw new InputError(`${functionName}: ${label}.columns must be an array of NON-EMPTY column-name strings — a ` +
+                `column with no name cannot be addressed by any consumer that fetches the table.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: functionName, field: `${label}.columns` },
+            });
+        }
+        const seenColumns = new Set();
+        for (const column of handle.columns) {
+            if (seenColumns.has(column)) {
+                throw new InputError(`${functionName}: ${label}.columns names "${column}" twice — column names are the table's ` +
+                    `column identity, so a duplicate makes "which column is ${JSON.stringify(column)}?" ` +
+                    'unanswerable for every consumer. Rename or drop one.', {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${label}.columns`, column },
+                });
+            }
+            seenColumns.add(column);
+        }
+        if (handle.columns.length !== columnCount) {
+            throw new InputError(`${functionName}: ${label}.columns names ${handle.columns.length} column${handle.columns.length === 1 ? '' : 's'} but columnCount is ${columnCount} — the two must agree.`, {
+                code: ErrorCode.InputLengthMismatch,
+                context: {
+                    function: functionName,
+                    field: `${label}.columns`,
+                    columns: handle.columns.length,
+                    columnCount,
+                },
+            });
+        }
+    }
+    if (handle.locator !== undefined &&
+        (typeof handle.locator !== 'string' || handle.locator.length === 0)) {
+        throw new InputError(`${functionName}: ${label}.locator must be a non-empty storage-reference string when present (a path, URL, or cache key the storage layer understands). Received ${handle.locator === null ? 'null' : typeof handle.locator === 'string' ? "''" : typeof handle.locator}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${label}.locator` },
+        });
+    }
+    if (handle.mediaType !== undefined &&
+        (typeof handle.mediaType !== 'string' || handle.mediaType.length === 0)) {
+        throw new InputError(`${functionName}: ${label}.mediaType must be a non-empty media-type string when present (e.g. 'application/json') — an empty encoding name tells the fetching side nothing. Received ${handle.mediaType === null ? 'null' : typeof handle.mediaType === 'string' ? "''" : typeof handle.mediaType}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${label}.mediaType` },
+        });
+    }
+    return value;
+}
+/**
+ * Structural PREDICATE for a table handle: the COMPLETE {@link requireTableHandle} validation
+ * behind a boolean door, so `value is TableHandle` is a sound claim — `true` means every envelope
+ * site would accept the handle unchanged. (An earlier version checked only the required fields, so
+ * `{ …, columns: 42 }` passed the guard and then detonated at the first validation site; a guard
+ * that is a weaker law than the validator is a `false` dressed as a `true`.) It runs the full
+ * field walk — not a constant-time tag sniff — which for a handle (a dozen scalar fields) is still
+ * trivially cheap.
+ */
+export function isTableHandle(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    try {
+        requireTableHandle('isTableHandle', 'value', value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a validated, frozen table handle.
+ *
+ * @example
+ * ```ts
+ * const handle = createTableHandle({
+ *   contentHash: contentHash(chainRows),
+ *   rowCount: chainRows.length,
+ *   columnCount: 8,
+ *   columns: ['strike', 'expiry', 'bid', 'ask', 'mid', 'volume', 'openInterest', 'impliedVolatility'],
+ *   locator: 'artifacts/chains/aapl-2026-07-20.json',
+ * });
+ * ```
+ */
+export function createTableHandle(input) {
+    requireArgumentObject('createTableHandle', 'input', input);
+    ensureKnownKeys('createTableHandle', 'input', input, [
+        'contentHash',
+        'rowCount',
+        'columnCount',
+        'columns',
+        'locator',
+        'mediaType',
+    ]);
+    // ONE validator: creation routes through the same full check every envelope site applies to a
+    // stored handle, so create-time and read-time can never disagree about what a handle is.
+    const validated = requireTableHandle('createTableHandle', 'input', {
+        kind: TABLE_HANDLE_KIND,
+        contentHash: input.contentHash,
+        rowCount: input.rowCount,
+        columnCount: input.columnCount,
+        ...(input.columns !== undefined ? { columns: input.columns } : {}),
+        ...(input.locator !== undefined ? { locator: input.locator } : {}),
+        ...(input.mediaType !== undefined ? { mediaType: input.mediaType } : {}),
+    });
+    return Object.freeze({
+        kind: TABLE_HANDLE_KIND,
+        contentHash: validated.contentHash,
+        rowCount: validated.rowCount,
+        columnCount: validated.columnCount,
+        ...(validated.columns !== undefined
+            ? { columns: Object.freeze([...validated.columns]) }
+            : {}),
+        ...(validated.locator !== undefined ? { locator: validated.locator } : {}),
+        ...(validated.mediaType !== undefined ? { mediaType: validated.mediaType } : {}),
+    });
+}
+const ROWS_HANDLE_KEYS = ['rows', 'locator', 'mediaType'];
+/**
+ * Mint the table handle for a row set the caller holds (Stage 4.5 Decision 4 — the ONE column law
+ * every package shares, so the same rows always mint the same handle):
+ *
+ * - an array of plain records → `columns` is the sorted union of the rows' own keys;
+ * - an array of numbers (a returns or realized-variance vector) → one column, `['value']`;
+ * - anything else (mixed rows, nested arrays, non-plain objects) is refused with the teaching.
+ *
+ * `contentHash` is the canonical-JSON hash of the rows exactly as given, so a consumer that later
+ * receives rows can prove they are the referenced ones by re-minting and comparing hashes.
+ *
+ * @example
+ * ```ts
+ * const handle = tableHandleForRows({ rows: observations, locator: 'universe/2026-09-01.json' });
+ * // { kind: 'totalfinance.table-handle', contentHash: 'sha256:…', rowCount: 4200, columnCount: 3, columns: ['availableTimestampMs', 'fields', 'instrumentId'] }
+ * ```
+ */
+export function tableHandleForRows(input) {
+    const functionName = 'tableHandleForRows';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ROWS_HANDLE_KEYS);
+    const rows = input.rows;
+    if (!Array.isArray(rows)) {
+        throw new InputError(`${functionName}: input.rows must be an array of rows (plain records or numbers). Received ${rows === null ? 'null' : typeof rows}.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field: 'input.rows' } });
+    }
+    // Prove the rows are behavior-free stored data (dense, plain, acyclic) before reading or hashing them.
+    scanCanonicalData(rows, { functionName, label: 'input.rows' });
+    let columns;
+    if (rows.length === 0) {
+        columns = [];
+    }
+    else if (rows.every((row) => typeof row === 'number')) {
+        columns = ['value'];
+    }
+    else if (rows.every((row) => row !== null &&
+        typeof row === 'object' &&
+        !Array.isArray(row) &&
+        (Object.getPrototypeOf(row) === Object.prototype || Object.getPrototypeOf(row) === null))) {
+        const union = new Set();
+        for (const row of rows) {
+            for (const key of Object.keys(row))
+                union.add(key);
+        }
+        columns = [...union].sort();
+        if (columns.some((column) => column.length === 0)) {
+            throw new InputError(`${functionName}: input.rows contains a record with an empty-string key — a column with no name cannot be addressed by any consumer.`, {
+                code: ErrorCode.InputWrongShape,
+                context: { function: functionName, field: 'input.rows' },
+            });
+        }
+    }
+    else {
+        throw new InputError(`${functionName}: input.rows must be EITHER an array of plain records (one column per key) OR an array of numbers (one 'value' column) — mixed or nested rows have no single column law. Project them to records first, e.g. rows.map((value, index) => ({ index, value })).`, { code: ErrorCode.InputWrongShape, context: { function: functionName, field: 'input.rows' } });
+    }
+    return createTableHandle({
+        contentHash: contentHash(rows),
+        rowCount: rows.length,
+        columnCount: columns.length,
+        ...(columns.length > 0 ? { columns } : {}),
+        ...(input.locator !== undefined ? { locator: input.locator } : {}),
+        ...(input.mediaType !== undefined ? { mediaType: input.mediaType } : {}),
+    });
+}
+//# sourceMappingURL=table-handle.js.map

package/modules/core/dist/artifacts/table-handle.js.map

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

package/modules/core/dist/assumptions.d.ts

@@ -0,0 +1,52 @@
+/** Convention disclosure (spec §7.4). Pro results echo every applied convention here. */
+import type { InterestCompounding, DayCount, EpochMs } from './time.js';
+/** Bump this only when default conventions change (major versions only, design law #3). */
+export declare const CONVENTIONS_VERSION = "0.0.1";
+export type ThetaUnit = 'perDay' | 'perYear';
+export type VegaUnit = 'per1Percent' | 'perPoint';
+export type RhoUnit = 'per1Percent' | 'perPoint';
+/** Units in which Greeks are reported. */
+export interface GreekUnits {
+    theta: ThetaUnit;
+    vega: VegaUnit;
+    rho: RhoUnit;
+}
+export type DividendModel = 'none' | 'continuousYield' | 'discreteSchedule';
+/**
+ * Assumptions echoed on every pro result. Extra model-specific fields are added via the `Extra`
+ * type parameter so each domain can annotate its own conventions without losing the common shape.
+ */
+export type Assumptions<Extra extends Record<string, unknown> = Record<never, never>> = {
+    conventionsVersion: string;
+    dayCount?: DayCount;
+    compounding?: InterestCompounding;
+    calendar?: string;
+    calendarVersion?: string;
+    asOf?: EpochMs;
+    timeToExpiryYears?: number;
+    /**
+     * How the contract's expiry label was resolved to an instant: `'us-equity-close'` when a
+     * date-only `YYYY-MM-DD` expiry resolved to the US equity/options close — 16:00 America/New_York,
+     * or 13:00 on an early-close day;
+     * `'explicit-instant'` when the caller supplied a zoned datetime. Named so the convention is
+     * never silent (alignment spec P1.6); instrument builders own the full story in Phase 3.
+     */
+    expiryConvention?: 'us-equity-close' | 'explicit-instant';
+    timeToExpiryConvention?: never;
+    dividendModel?: DividendModel;
+    units?: GreekUnits;
+    model?: string;
+    engine?: string;
+    /**
+     * The randomness seed this result was computed under — REQUIRED echo for a
+     * `randomness: 'seeded'` Pricer (Gate C, 2026-08-23): a stochastic result that does not name
+     * its seed cannot be replayed from the result alone. Deterministic paths never set it.
+     */
+    seed?: number;
+} & Extra;
+/** Library default conventions (spec §7.4 defaults table). */
+export declare const DEFAULT_DAY_COUNT: DayCount;
+export declare const DEFAULT_COMPOUNDING: InterestCompounding;
+export declare const DEFAULT_DIVIDEND_YIELD = 0;
+export declare const DEFAULT_GREEK_UNITS: GreekUnits;
+//# sourceMappingURL=assumptions.d.ts.map

package/modules/core/dist/assumptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.d.ts","sourceRoot":"","sources":["../src/assumptions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AAEzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAExE,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC7C,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,UAAU,CAAC;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE5E;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI;IACtF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,kBAAkB,CAAC;IAC1D,sBAAsB,CAAC,EAAE,KAAK,CAAC;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,KAAK,CAAC;AAEV,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,EAAE,QAAqB,CAAC;AACtD,eAAO,MAAM,mBAAmB,EAAE,mBAAkC,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,mBAAmB,EAAE,UAIjC,CAAC"}

package/modules/core/dist/assumptions.js

@@ -0,0 +1,13 @@
+/** Convention disclosure (spec §7.4). Pro results echo every applied convention here. */
+/** Bump this only when default conventions change (major versions only, design law #3). */
+export const CONVENTIONS_VERSION = '0.0.1';
+/** Library default conventions (spec §7.4 defaults table). */
+export const DEFAULT_DAY_COUNT = 'ACT/365F';
+export const DEFAULT_COMPOUNDING = 'continuous';
+export const DEFAULT_DIVIDEND_YIELD = 0;
+export const DEFAULT_GREEK_UNITS = {
+    theta: 'perDay',
+    vega: 'per1Percent',
+    rho: 'per1Percent',
+};
+//# sourceMappingURL=assumptions.js.map

package/modules/core/dist/assumptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.js","sourceRoot":"","sources":["../src/assumptions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AAIzF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAgD3C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,iBAAiB,GAAa,UAAU,CAAC;AACtD,MAAM,CAAC,MAAM,mBAAmB,GAAwB,YAAY,CAAC;AACrE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,aAAa;CACnB,CAAC"}

package/modules/core/dist/calendar.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Calendar interface, rules engine, and tiny calendars (spec §7.3, §22.4).
+ *
+ * Core owns the *machinery* (the interface, roll/observance rules, holiday-rule generators, and the
+ * `createRuleCalendar` factory) and two tiny calendars that need no holiday datasets (`alwaysOpen`,
+ * `weekendsOnly`). Exchange-specific holiday *data* lives in `@insiderfinance/totalfinance/calendars`, so core never
+ * bundles exchange datasets.
+ */
+/** Day of week, Sunday = 0 … Saturday = 6. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export interface DaySession {
+    date: string;
+    isBusinessDay: boolean;
+    isHalfDay: boolean;
+    /** Local `HH:MM` open (present only on business days). */
+    open?: string;
+    /** Local `HH:MM` close (early close on half days). */
+    close?: string;
+}
+export interface Calendar {
+    readonly name: string;
+    readonly version: string;
+    readonly timezone: string;
+    isBusinessDay(date: string): boolean;
+    isHoliday(date: string): boolean;
+    isHalfDay(date: string): boolean;
+    nextBusinessDay(date: string): string;
+    previousBusinessDay(date: string): string;
+    addBusinessDays(date: string, days: number): string;
+    /** Business days in the half-open interval `(from, to]` (negative if `to < from`). */
+    businessDaysBetween(from: string, to: string): number;
+    session(date: string): DaySession;
+}
+/** Day of week for an ISO date. */
+export declare function dayOfWeek(date: string): Weekday;
+/** Add `n` calendar days to an ISO date. */
+export declare function addDays(date: string, days: number): string;
+/** Compose an ISO date from components. */
+export declare function ymd(year: number, month: number, day: number): string;
+/**
+ * The `occurrence`-th (1-based) `weekday` of a month, e.g. 3rd Monday of January. Returns `null`
+ * when the month has no such occurrence (e.g. a 5th Friday in a 4-Friday February) — the same
+ * "not observed" channel {@link HolidayRule} already speaks — rather than fabricating an
+ * impossible date like `2026-02-34`.
+ */
+export declare function nthWeekdayOfMonth(year: number, month: number, weekday: Weekday, occurrence: number): string | null;
+/** The last `weekday` of a month, e.g. last Monday of May. */
+export declare function lastWeekdayOfMonth(year: number, month: number, weekday: Weekday): string;
+/** Apply the US observance rule: Saturday → preceding Friday, Sunday → following Monday. */
+export declare function observedHoliday(year: number, month: number, day: number): string;
+/** Easter Sunday via the Anonymous Gregorian algorithm (Computus). */
+export declare function easterSunday(year: number): {
+    month: number;
+    day: number;
+};
+/** Good Friday (two days before Easter Sunday). */
+export declare function goodFriday(year: number): string;
+/** A holiday/half-day rule: given a year, return the ISO date it falls on, or `null` if not observed. */
+export type HolidayRule = (year: number) => string | null;
+export interface CalendarConfig {
+    name: string;
+    version: string;
+    timezone: string;
+    /** Default `[0, 6]` (Sun & Sat). */
+    weekendDays?: Weekday[];
+    /**
+     * Regular session hours as `HH:MM` in the calendar's `timezone`. `close: '24:00'` is the sentinel
+     * for "no close" — a continuous 24-hour session (e.g. `alwaysOpen`/crypto), distinct from `'00:00'`
+     * (midnight). Keep it as `'24:00'`; do not normalize to `'00:00'`.
+     */
+    session: {
+        open: string;
+        close: string;
+        halfDayClose?: string;
+    };
+    holidayRules?: HolidayRule[];
+    halfDayRules?: HolidayRule[];
+    /** Ad-hoc full closures (ISO dates), e.g. emergency closures or days of mourning. */
+    closures?: string[];
+}
+/**
+ * Build a `Calendar` from rules. Holiday/half-day sets are computed lazily per year and cached.
+ *
+ * The config is SNAPSHOTTED at construction — rule arrays, closures, weekend days, and the session
+ * object are copied — so mutating the caller's config (or a shared exported rules array) later can
+ * never make one calendar answer the same question two ways across warm and cold cache years.
+ */
+export declare function createRuleCalendar(config: CalendarConfig): Calendar;
+/** A 24/7 calendar (every day is a business day) — e.g. crypto. */
+export declare const alwaysOpen: Calendar;
+/** A calendar whose only non-business days are weekends. */
+export declare const weekendsOnly: Calendar;
+/**
+ * Define a custom calendar (spec §22.4 extension API). A thin wrapper over `createRuleCalendar` so
+ * the extension surface is stable even if the engine evolves.
+ */
+export declare function defineCalendar(config: CalendarConfig): Calendar;
+//# sourceMappingURL=calendar.d.ts.map

package/modules/core/dist/calendar.d.ts.map

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