@insiderfinance/totalfinance 0.1.0

package/modules/core/dist/artifacts/fitted-model-summary.js

@@ -0,0 +1,254 @@
+/**
+ * The fitted-model summary grammar (Stage 4.5 Decision 2) — the ONE standard description of a
+ * calibrated model that every domain adapter projects from its direct calibrator's result:
+ * parameters, objective, convergence, residuals, model risk, weighting, input identity, and the
+ * family's integer model version. Structural and model-agnostic: core knows no calibrator, so this
+ * module validates SHAPE and honesty (a null objective carries a reason; a range has a minimum at
+ * or below its maximum; hashes are hashes) and nothing about what the numbers mean.
+ *
+ * The summary is a PROJECTION — the domain report beside it carries the verbatim fit, and replay
+ * compares the fit, never the summary.
+ */
+import { ErrorCode, InputError } from '../errors.js';
+import { ensureKnownKeys, requireArgumentObject } from '../invariants.js';
+import { scanCanonicalData } from './canonical-scan.js';
+import { isContentHashString } from './content-hash.js';
+const SUMMARY_KEYS = [
+    'family',
+    'modelVersion',
+    'parameters',
+    'objective',
+    'convergence',
+    'residuals',
+    'modelRisk',
+    'weighting',
+    'inputIdentity',
+    'warningCount',
+];
+const OBJECTIVE_KINDS = [
+    'root-mean-square-error',
+    'log-likelihood',
+    'r-squared',
+    'exact-fit',
+    'exact-bootstrap',
+    'not-applicable',
+];
+const RESIDUAL_SOURCES = [
+    'reported-by-calibrator',
+    'direct-evaluator',
+];
+const FAMILY_PATTERN = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/;
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number')
+        return String(value);
+    return typeof value;
+}
+function fail(functionName, path, message, code) {
+    throw new InputError(`${functionName}: ${path} ${message}`, {
+        code,
+        context: { function: functionName, field: path },
+    });
+}
+function requireString(functionName, path, value, what) {
+    if (typeof value !== 'string' || value.length === 0) {
+        fail(functionName, path, `must be ${what} (a non-empty string). Received ${describe(value)}.`, ErrorCode.InputWrongType);
+    }
+    return value;
+}
+function requireFiniteNumber(functionName, path, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        fail(functionName, path, `must be a finite number. Received ${describe(value)}.`, typeof value === 'number'
+            ? Number.isNaN(value)
+                ? ErrorCode.InputNaN
+                : ErrorCode.InputNotFinite
+            : ErrorCode.InputWrongType);
+    }
+    return value;
+}
+function requireFiniteOrNull(functionName, path, value) {
+    if (value === null)
+        return null;
+    return requireFiniteNumber(functionName, path, value);
+}
+function requireNonNegativeInteger(functionName, path, value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        fail(functionName, path, `must be a non-negative safe integer. Received ${describe(value)}.`, ErrorCode.InputOutOfRange);
+    }
+    return value;
+}
+function requireBoolean(functionName, path, value) {
+    if (typeof value !== 'boolean') {
+        fail(functionName, path, `must be a boolean. Received ${describe(value)}.`, ErrorCode.InputWrongType);
+    }
+    return value;
+}
+function requireRecord(functionName, path, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail(functionName, path, `must be a plain object. Received ${describe(value)}.`, ErrorCode.InputWrongType);
+    }
+    return value;
+}
+function requireLiteral(functionName, path, value, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        fail(functionName, path, `must be one of ${allowed.join(', ')}. Received ${describe(value)}.`, ErrorCode.InputInvalidEnum);
+    }
+    return value;
+}
+function requireOptionalReason(functionName, path, value) {
+    if (value !== undefined && (typeof value !== 'string' || value.length === 0)) {
+        fail(functionName, path, `must be a non-empty prose reason when present. Received ${describe(value)}.`, ErrorCode.InputWrongType);
+    }
+}
+/**
+ * The FULL summary validator — closed keys at every level, typed and finite fields, and the
+ * honesty rules (a null objective or residual statistic needs its reason; a calibrated range is
+ * ordered; identity fields are content hashes). Shared by the domain adapters (which project a
+ * summary and then prove it here) and by {@link isFittedModelSummary}. Returns the validated value.
+ */
+export function requireFittedModelSummary(functionName, label, value) {
+    requireArgumentObject(functionName, label, value);
+    // Hostile shapes (accessors, cycles, class instances) are refused before any field is read.
+    scanCanonicalData(value, { functionName, label, maximumDepth: 8, requireFiniteNumbers: true });
+    const summary = value;
+    ensureKnownKeys(functionName, label, summary, SUMMARY_KEYS);
+    for (const key of SUMMARY_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(summary, key)) {
+            fail(functionName, `${label}.${key}`, 'is required — a fitted-model summary states every field, with null where a notion does not apply.', ErrorCode.InputMissingField);
+        }
+    }
+    const family = requireString(functionName, `${label}.family`, summary['family'], 'a dot-namespaced family');
+    if (!FAMILY_PATTERN.test(family)) {
+        fail(functionName, `${label}.family`, `must be '<package>.<family>' in lower-case kebab words, e.g. 'volatility.ssvi'. Received ${JSON.stringify(family)}.`, ErrorCode.InputWrongShape);
+    }
+    const modelVersion = summary['modelVersion'];
+    if (typeof modelVersion !== 'number' || !Number.isSafeInteger(modelVersion) || modelVersion < 1) {
+        fail(functionName, `${label}.modelVersion`, `must be a positive integer model version. Received ${describe(modelVersion)}.`, ErrorCode.InputOutOfRange);
+    }
+    const parameters = requireRecord(functionName, `${label}.parameters`, summary['parameters']);
+    for (const [name, parameter] of Object.entries(parameters)) {
+        const path = `${label}.parameters.${name}`;
+        if (name.length === 0)
+            fail(functionName, `${label}.parameters`, 'has an empty parameter name.', ErrorCode.InputWrongShape);
+        if (typeof parameter === 'string') {
+            if (parameter.length === 0)
+                fail(functionName, path, 'must be a non-empty string when a parameter is a label.', ErrorCode.InputWrongType);
+            continue;
+        }
+        if (Array.isArray(parameter)) {
+            parameter.forEach((element, index) => requireFiniteNumber(functionName, `${path}[${index}]`, element));
+            continue;
+        }
+        if (typeof parameter !== 'number') {
+            fail(functionName, path, `must be a finite number, an array of finite numbers, or a string label. Received ${describe(parameter)}.`, ErrorCode.InputWrongType);
+        }
+        requireFiniteNumber(functionName, path, parameter);
+    }
+    const objective = requireRecord(functionName, `${label}.objective`, summary['objective']);
+    ensureKnownKeys(functionName, `${label}.objective`, objective, [
+        'kind',
+        'value',
+        'unit',
+        'reason',
+    ]);
+    requireLiteral(functionName, `${label}.objective.kind`, objective['kind'], OBJECTIVE_KINDS);
+    const objectiveValue = requireFiniteOrNull(functionName, `${label}.objective.value`, objective['value']);
+    requireString(functionName, `${label}.objective.unit`, objective['unit'], "the objective's unit or basis");
+    requireOptionalReason(functionName, `${label}.objective.reason`, objective['reason']);
+    if (objectiveValue === null && objective['reason'] === undefined) {
+        fail(functionName, `${label}.objective.reason`, 'is required when objective.value is null — an undefined objective states why (law 7: null with a reason, never a bare null).', ErrorCode.InputMissingField);
+    }
+    if (objectiveValue !== null && objective['reason'] !== undefined) {
+        fail(functionName, `${label}.objective.reason`, 'is present although objective.value is a number — a reason accompanies a null value only.', ErrorCode.InputWrongShape);
+    }
+    const convergence = requireRecord(functionName, `${label}.convergence`, summary['convergence']);
+    ensureKnownKeys(functionName, `${label}.convergence`, convergence, [
+        'converged',
+        'iterations',
+        'reason',
+    ]);
+    requireBoolean(functionName, `${label}.convergence.converged`, convergence['converged']);
+    if (convergence['iterations'] !== null) {
+        requireNonNegativeInteger(functionName, `${label}.convergence.iterations`, convergence['iterations']);
+    }
+    requireOptionalReason(functionName, `${label}.convergence.reason`, convergence['reason']);
+    if (summary['residuals'] !== null) {
+        const residuals = requireRecord(functionName, `${label}.residuals`, summary['residuals']);
+        ensureKnownKeys(functionName, `${label}.residuals`, residuals, [
+            'count',
+            'rootMeanSquare',
+            'maximumAbsolute',
+            'unit',
+            'source',
+        ]);
+        requireNonNegativeInteger(functionName, `${label}.residuals.count`, residuals['count']);
+        for (const field of ['rootMeanSquare', 'maximumAbsolute']) {
+            const statistic = requireFiniteOrNull(functionName, `${label}.residuals.${field}`, residuals[field]);
+            if (statistic !== null && statistic < 0) {
+                fail(functionName, `${label}.residuals.${field}`, `must be ≥ 0 (a magnitude). Received ${statistic}.`, ErrorCode.InputOutOfRange);
+            }
+        }
+        requireString(functionName, `${label}.residuals.unit`, residuals['unit'], "the residuals' unit");
+        requireLiteral(functionName, `${label}.residuals.source`, residuals['source'], RESIDUAL_SOURCES);
+    }
+    const modelRisk = requireRecord(functionName, `${label}.modelRisk`, summary['modelRisk']);
+    ensureKnownKeys(functionName, `${label}.modelRisk`, modelRisk, [
+        'arbitrageFree',
+        'calibratedRange',
+        'notes',
+    ]);
+    if (modelRisk['arbitrageFree'] !== null) {
+        requireBoolean(functionName, `${label}.modelRisk.arbitrageFree`, modelRisk['arbitrageFree']);
+    }
+    const ranges = requireRecord(functionName, `${label}.modelRisk.calibratedRange`, modelRisk['calibratedRange']);
+    for (const [coordinate, range] of Object.entries(ranges)) {
+        const path = `${label}.modelRisk.calibratedRange.${coordinate}`;
+        const record = requireRecord(functionName, path, range);
+        ensureKnownKeys(functionName, path, record, ['minimum', 'maximum']);
+        const minimum = requireFiniteNumber(functionName, `${path}.minimum`, record['minimum']);
+        const maximum = requireFiniteNumber(functionName, `${path}.maximum`, record['maximum']);
+        if (minimum > maximum) {
+            fail(functionName, path, `must be ordered: minimum ${minimum} is above maximum ${maximum}.`, ErrorCode.InputOutOfRange);
+        }
+    }
+    const notes = modelRisk['notes'];
+    if (!Array.isArray(notes) ||
+        notes.some((note) => typeof note !== 'string' || note.length === 0)) {
+        fail(functionName, `${label}.modelRisk.notes`, 'must be an array of non-empty prose notes (empty is fine, absent is not).', ErrorCode.InputWrongType);
+    }
+    if (summary['weighting'] !== null) {
+        requireString(functionName, `${label}.weighting`, summary['weighting'], "the calibrator's weighting");
+    }
+    const identity = requireRecord(functionName, `${label}.inputIdentity`, summary['inputIdentity']);
+    ensureKnownKeys(functionName, `${label}.inputIdentity`, identity, [
+        'calibrationHash',
+        'snapshotHash',
+    ]);
+    if (!isContentHashString(identity['calibrationHash'])) {
+        fail(functionName, `${label}.inputIdentity.calibrationHash`, `must be a 'sha256:<64 hex>' content hash of the calibration input — build it with contentHash(calibration). Received ${describe(identity['calibrationHash'])}.`, ErrorCode.InputWrongType);
+    }
+    if (identity['snapshotHash'] !== null && !isContentHashString(identity['snapshotHash'])) {
+        fail(functionName, `${label}.inputIdentity.snapshotHash`, `must be a 'sha256:<64 hex>' market-snapshot hash or null. Received ${describe(identity['snapshotHash'])}.`, ErrorCode.InputWrongType);
+    }
+    requireNonNegativeInteger(functionName, `${label}.warningCount`, summary['warningCount']);
+    return value;
+}
+/**
+ * Sound structural predicate for a fitted-model summary: the COMPLETE {@link requireFittedModelSummary}
+ * validation behind a boolean door, so `value is FittedModelSummary` is a claim every consumer can act on.
+ */
+export function isFittedModelSummary(value) {
+    try {
+        requireFittedModelSummary('isFittedModelSummary', 'value', value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=fitted-model-summary.js.map

package/modules/core/dist/artifacts/fitted-model-summary.js.map

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

package/modules/core/dist/artifacts/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `@insiderfinance/totalfinance/core/artifacts` — the shared artifact spine (platform Gate B).
+ *
+ * One grammar for the things every layer above compute wants to SAVE, SHARE, and REPLAY:
+ *
+ * - {@link createMarketSnapshot} / {@link readMarketSnapshot} — "market state at an instant" as a
+ *   versioned, immutable, JSON-safe envelope with explicit conventions and caller-supplied
+ *   provenance;
+ * - {@link createAnalysisArtifact} / {@link readAnalysisArtifact} — a computed Law-2 result as a
+ *   durable record with a content-hash identity, an inputs hash, a `createdFrom` lineage chain,
+ *   and {@link TableHandle} references instead of inlined large tables;
+ * - {@link createScenarioSet} / {@link readScenarioSet} — named shock/override definitions as pure
+ *   data, in the same shock vocabulary `@insiderfinance/totalfinance/risk` already prices;
+ * - {@link canonicalJsonOf} / {@link contentHash} — the canonical serialization and SHA-256
+ *   identity everything above hashes with;
+ * - {@link createArtifactMigrationRegistry} — the explicit, never-silent schema-migration policy
+ *   every reader shares.
+ *
+ * This is a SEPARATE entrypoint on purpose, exactly like `@insiderfinance/totalfinance/core/schema` (spec §6 hot-path
+ * rule): compute entrypoints import `@insiderfinance/totalfinance/core` and never this module, so serialization and
+ * hashing stay out of pricing bundles. Nothing here fetches, reads the clock, or touches storage —
+ * the spine defines CONTAINERS; runners (Gate D) and stores (data plane) come later and consume it.
+ *
+ * JSON-safe first; Arrow reserved: every envelope here has one canonical JSON form. A lossless
+ * Arrow mapping for large tables is a reserved contract on {@link TableHandle} (same content hash
+ * over the canonical row projection), to be implemented only when a measured large-table consumer
+ * exists — performance work is deliberately deferred in this repo.
+ */
+export { CANONICAL_JSON_VERSION, canonicalJsonOf, fromCanonicalJson, isNonFiniteNumber, } from '../canonical-json.js';
+export type { NonFiniteNumber } from '../canonical-json.js';
+export { CONTENT_HASH_PREFIX, contentHash, isContentHashString, sha256Hex, } from './content-hash.js';
+export { createArtifactMigrationRegistry } from './migration.js';
+export type { AppliedMigration, ArtifactMigration, ArtifactMigrationRegistry, } from './migration.js';
+export { TABLE_HANDLE_KIND, TABLE_MEDIA_TYPE_ARROW_RESERVED, createTableHandle, isTableHandle, tableHandleForRows, } from './table-handle.js';
+export { CANONICAL_DATA_MAX_DEPTH, canonicalStringWorkUnits, scanCanonicalData, } from './canonical-scan.js';
+export type { CanonicalDataScanOptions } from './canonical-scan.js';
+export { COMPARISON_LIMITS, artifactReplayParity, compareAnalysisArtifacts } from './comparison.js';
+export { compareCalculationArtifacts } from './calculation-comparison.js';
+export type { CalculationArtifactComparison, CalculationComparisonReason, CalculationMetric, CalculationMetricComparison, CalculationMetricObservation, CalculationMetricSelector, CalculationMetricUnavailableReason, CalculationOperationPolicy, CalculationSourceDiagnostics, CompareCalculationArtifactsInput, } from './calculation-comparison.js';
+export type { ArtifactComparison, ArtifactReplayParity, ComparisonLimits, ComparisonTolerance, ValueDifference, } from './comparison.js';
+export { isFittedModelSummary, requireFittedModelSummary } from './fitted-model-summary.js';
+export { ARTIFACT_WORK_LIMITS, applyReportMigrations, flattenSummaryParameters, requireComparisonTolerance, requireWorkLimit, residualStatistics, verifyReferencedRows, } from './fitted-model-kit.js';
+export type { WorkLimitLaw } from './fitted-model-kit.js';
+export type { FittedModelObjectiveKind, FittedModelResidualSource, FittedModelSummary, } from './fitted-model-summary.js';
+export type { TableHandle } from './table-handle.js';
+export { MARKET_SNAPSHOT_KIND, MARKET_SNAPSHOT_SCHEMA_VERSION, createMarketSnapshot, requireInstantMarketSnapshot, isMarketSnapshot, marketSnapshotContentHash, readMarketSnapshot, } from './market-snapshot.js';
+export type { CreateMarketSnapshotInput, CreateMarketSnapshotInputConventions, MarketSnapshot, MarketSnapshotAsOfConvention, MarketSnapshotConventions, MarketSnapshotObservations, OptionChainObservation, SpotObservation, VolatilitySurfaceObservation, } from './market-snapshot.js';
+export { ANALYSIS_ARTIFACT_KIND, ANALYSIS_ARTIFACT_SCHEMA_VERSION, createAnalysisArtifact, isAnalysisArtifact, readAnalysisArtifact, } from './analysis-artifact.js';
+export type { AnalysisArtifact, ArtifactInputs, ArtifactProducedBy } from './analysis-artifact.js';
+export { SCENARIO_SET_KIND, SCENARIO_SET_SCHEMA_VERSION, createScenarioSet, isScenarioSet, readScenarioSet, scenarioSetContentHash, } from './scenario-set.js';
+export type { ScenarioDefinition, ScenarioFactor, ScenarioOverride, ScenarioSet, ScenarioShock, } from './scenario-set.js';
+//# sourceMappingURL=index.d.ts.map

package/modules/core/dist/artifacts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,EAC5B,yBAAyB,EACzB,kCAAkC,EAClC,0BAA0B,EAC1B,4BAA4B,EAC5B,gCAAgC,GACjC,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,yBAAyB,EACzB,oCAAoC,EACpC,cAAc,EACd,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,eAAe,EACf,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEnG,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/modules/core/dist/artifacts/index.js

@@ -0,0 +1,47 @@
+/**
+ * `@insiderfinance/totalfinance/core/artifacts` — the shared artifact spine (platform Gate B).
+ *
+ * One grammar for the things every layer above compute wants to SAVE, SHARE, and REPLAY:
+ *
+ * - {@link createMarketSnapshot} / {@link readMarketSnapshot} — "market state at an instant" as a
+ *   versioned, immutable, JSON-safe envelope with explicit conventions and caller-supplied
+ *   provenance;
+ * - {@link createAnalysisArtifact} / {@link readAnalysisArtifact} — a computed Law-2 result as a
+ *   durable record with a content-hash identity, an inputs hash, a `createdFrom` lineage chain,
+ *   and {@link TableHandle} references instead of inlined large tables;
+ * - {@link createScenarioSet} / {@link readScenarioSet} — named shock/override definitions as pure
+ *   data, in the same shock vocabulary `@insiderfinance/totalfinance/risk` already prices;
+ * - {@link canonicalJsonOf} / {@link contentHash} — the canonical serialization and SHA-256
+ *   identity everything above hashes with;
+ * - {@link createArtifactMigrationRegistry} — the explicit, never-silent schema-migration policy
+ *   every reader shares.
+ *
+ * This is a SEPARATE entrypoint on purpose, exactly like `@insiderfinance/totalfinance/core/schema` (spec §6 hot-path
+ * rule): compute entrypoints import `@insiderfinance/totalfinance/core` and never this module, so serialization and
+ * hashing stay out of pricing bundles. Nothing here fetches, reads the clock, or touches storage —
+ * the spine defines CONTAINERS; runners (Gate D) and stores (data plane) come later and consume it.
+ *
+ * JSON-safe first; Arrow reserved: every envelope here has one canonical JSON form. A lossless
+ * Arrow mapping for large tables is a reserved contract on {@link TableHandle} (same content hash
+ * over the canonical row projection), to be implemented only when a measured large-table consumer
+ * exists — performance work is deliberately deferred in this repo.
+ */
+// Canonical JSON lives at the core root (a generic serialization utility, shared with the Gate C
+// conformance kit — moved out of `artifacts/` 2026-08-23); this barrel keeps re-exporting it so
+// the public `@insiderfinance/totalfinance/core/artifacts` surface is unchanged by the move.
+export { CANONICAL_JSON_VERSION, canonicalJsonOf, fromCanonicalJson, isNonFiniteNumber, } from '../canonical-json.js';
+export { CONTENT_HASH_PREFIX, contentHash, isContentHashString, sha256Hex, } from './content-hash.js';
+export { createArtifactMigrationRegistry } from './migration.js';
+export { TABLE_HANDLE_KIND, TABLE_MEDIA_TYPE_ARROW_RESERVED, createTableHandle, isTableHandle, tableHandleForRows, } from './table-handle.js';
+// Stage 4.5 — the bounded stored-data scanner (promoted from the scenario runner), the structural
+// comparison / replay-parity laws, and the fitted-model summary grammar every calibration adapter
+// projects into.
+export { CANONICAL_DATA_MAX_DEPTH, canonicalStringWorkUnits, scanCanonicalData, } from './canonical-scan.js';
+export { COMPARISON_LIMITS, artifactReplayParity, compareAnalysisArtifacts } from './comparison.js';
+export { compareCalculationArtifacts } from './calculation-comparison.js';
+export { isFittedModelSummary, requireFittedModelSummary } from './fitted-model-summary.js';
+export { ARTIFACT_WORK_LIMITS, applyReportMigrations, flattenSummaryParameters, requireComparisonTolerance, requireWorkLimit, residualStatistics, verifyReferencedRows, } from './fitted-model-kit.js';
+export { MARKET_SNAPSHOT_KIND, MARKET_SNAPSHOT_SCHEMA_VERSION, createMarketSnapshot, requireInstantMarketSnapshot, isMarketSnapshot, marketSnapshotContentHash, readMarketSnapshot, } from './market-snapshot.js';
+export { ANALYSIS_ARTIFACT_KIND, ANALYSIS_ARTIFACT_SCHEMA_VERSION, createAnalysisArtifact, isAnalysisArtifact, readAnalysisArtifact, } from './analysis-artifact.js';
+export { SCENARIO_SET_KIND, SCENARIO_SET_SCHEMA_VERSION, createScenarioSet, isScenarioSet, readScenarioSet, scenarioSetContentHash, } from './scenario-set.js';
+//# sourceMappingURL=index.js.map

package/modules/core/dist/artifacts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,iGAAiG;AACjG,gGAAgG;AAChG,6FAA6F;AAC7F,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AAOjE,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,kGAAkG;AAClG,kGAAkG;AAClG,iBAAiB;AACjB,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAoB1E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EACL,sBAAsB,EACtB,gCAAgC,EAChC,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

package/modules/core/dist/artifacts/market-snapshot.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The versioned market snapshot (Gate B): ONE envelope for "market state at an instant", so books,
+ * scenarios, saved research, workers, and MCP handles stop inventing incompatible bags of market
+ * fields (roadmap Program 1).
+ *
+ * What the envelope IS:
+ *
+ * - **an instant** — `asOf`, resolved once through core's one time grammar (`resolveAsOf`); the
+ *   library never reads the machine clock, so the caller always supplies it;
+ * - **conventions, out loud** — `conventionsVersion` plus the day count / compounding / calendar
+ *   the flat observations are quoted under. A flat `riskFreeRates` section REQUIRES a stated
+ *   compounding and day count: a rate without its convention is not an observation, it is a guess
+ *   (the no-silent-economics law);
+ * - **observations** — spot/rate/dividend/volatility/curve/surface/chain sections that REUSE the
+ *   canonical `@insiderfinance/totalfinance/core` market-data vocabulary (`RateCurve`, `OptionQuote`) rather than
+ *   minting a second one, which is what lets existing per-domain market objects map in without
+ *   changing: an options `market({ spot, riskFreeRate, volatility, dividendYield, asOf })` is one
+ *   spot + one flat rate + one flat volatility + one flat dividend yield here, and a fixed-income
+ *   curve is already a `RateCurve`;
+ * - **provenance, caller-supplied** — the snapshot records where data CAME from; it never fetches
+ *   (explicit-effects law #7). Provenance is attached and preserved but excluded from the content
+ *   hash: two identically-valued snapshots from two vendors are the same market.
+ *
+ * What it is NOT: a required input. `blackScholes.call({...})` keeps taking `spot` and
+ * `riskFreeRate` directly (no-abstraction-tax law #5); the snapshot exists for calculations where
+ * sharing, replay, scenarios, or provenance justify it, and every observation remains plain
+ * readable data (escape-hatch law #6).
+ *
+ * Finiteness: a snapshot REFUSES non-finite numbers anywhere in its observations. An unobservable
+ * quantity is ABSENT, not `NaN` — which is also what makes the stored form pure JSON with no
+ * non-finite wrappers, so `JSON.stringify(snapshot)` is lossless as-is.
+ */
+import type { RateCurve, SymbolId } from '../market-data.js';
+import type { Provenance } from '../provenance.js';
+import type { DayCount, EpochMs, InterestCompounding } from '../time.js';
+import type { AppliedMigration, ArtifactMigrationRegistry } from './migration.js';
+import type { TableHandle } from './table-handle.js';
+export declare const MARKET_SNAPSHOT_KIND = "totalfinance.market-snapshot";
+/**
+ * Current market-snapshot schema version. Bump ONLY with a shape change, and land the bump with a
+ * registered migration — `readMarketSnapshot` refuses an older stored version without one, and
+ * refuses a newer version outright (this build cannot know what changed).
+ */
+export declare const MARKET_SNAPSHOT_SCHEMA_VERSION = 1;
+/** A spot observation. Open per Law 12: extra vendor fields are preserved, finite, and unread. */
+export interface SpotObservation {
+    /** Observed price in `currency`. Finite; sign unconstrained (negative commodity prints are real). */
+    price: number;
+    currency?: string;
+    /** When this particular print was observed, if it differs from the snapshot's `asOf`. */
+    timestampMs?: EpochMs;
+}
+/** An implied-volatility surface grid; `impliedVolatilities[i][j]` pairs expiry `i` with strike `j`. */
+export interface VolatilitySurfaceObservation {
+    timeToExpiryYears: number[];
+    strikes: number[];
+    /** Annualized decimal implied volatilities, row per expiry, column per strike. */
+    impliedVolatilities: number[][];
+}
+/**
+ * An option-chain observation: EITHER inline rows (small chains) or a {@link TableHandle}
+ * reference (large chains stay out of the envelope). Exactly one of the two.
+ * Rows are core `OptionQuote`-shaped and validated openly: the numeric fields TotalFinance consumes
+ * must be finite numbers when present; vendor decoration is preserved.
+ */
+export interface OptionChainObservation {
+    quotes?: Record<string, unknown>[];
+    table?: TableHandle;
+}
+export interface MarketSnapshotConventions {
+    /** The library conventions revision the snapshot was created under; stamped, not caller-set. */
+    conventionsVersion: string;
+    /**
+     * How `asOf` was expressed at create time; stamped, not caller-set. `'explicit-instant'` — epoch
+     * ms or a zoned datetime; `'date-midnight-utc'` — a bare `YYYY-MM-DD`, the ledger's date-granular
+     * convention (calendar date D at 00:00 UTC). Option-pricing consumers refuse a date-granular
+     * snapshot through {@link requireInstantMarketSnapshot}: the time of day prices a same-day option.
+     */
+    asOfConvention: MarketSnapshotAsOfConvention;
+    /** Quote basis for the flat `riskFreeRates`/`dividendYields` sections. Required with them. */
+    dayCount?: DayCount;
+    compounding?: InterestCompounding;
+    calendar?: string;
+}
+/** How a snapshot's `asOf` was expressed at create time (stamped by `createMarketSnapshot`). */
+export type MarketSnapshotAsOfConvention = 'explicit-instant' | 'date-midnight-utc';
+/**
+ * The caller-facing conventions at create time: everything in {@link MarketSnapshotConventions}
+ * EXCEPT `conventionsVersion` and `asOfConvention`, which the library stamps. Spelled out rather than `Omit<…>` so the
+ * declaration stays walkable by tooling and readable without resolving a mapped type.
+ */
+export interface CreateMarketSnapshotInputConventions {
+    /** Quote basis for the flat `riskFreeRates`/`dividendYields` sections. Required with them. */
+    dayCount?: DayCount;
+    compounding?: InterestCompounding;
+    calendar?: string;
+}
+/** Input for {@link createMarketSnapshot}. */
+export interface CreateMarketSnapshotInput {
+    /**
+     * Epoch ms or a zoned ISO datetime (stamped `asOfConvention: 'explicit-instant'`), or a bare
+     * `'YYYY-MM-DD'` for a date-granular ledger snapshot (calendar date D at 00:00 UTC, stamped
+     * `'date-midnight-utc'`). Option-pricing consumers refuse the date form with the fix.
+     */
+    asOf: EpochMs | string;
+    conventions?: CreateMarketSnapshotInputConventions;
+    observations: MarketSnapshotObservations;
+    /** Where the observations came from — supplied by the caller, never fetched (law #7). */
+    provenance?: Provenance;
+}
+export interface MarketSnapshotObservations {
+    spots?: Record<SymbolId, SpotObservation>;
+    /** Flat annual rates as decimals, keyed by currency, quoted under the envelope conventions. */
+    riskFreeRates?: Record<string, number>;
+    /** Flat continuous dividend/borrow yields as decimals, keyed by symbol. */
+    dividendYields?: Record<SymbolId, number>;
+    /** Flat annualized volatilities as decimals, keyed by symbol. */
+    volatilities?: Record<SymbolId, number>;
+    /** Full dated curves, keyed by a caller label (e.g. `'USD.sofr'`). Each carries its own conventions. */
+    curves?: Record<string, RateCurve>;
+    surfaces?: Record<SymbolId, VolatilitySurfaceObservation>;
+    chains?: Record<SymbolId, OptionChainObservation>;
+}
+export interface MarketSnapshot {
+    kind: typeof MARKET_SNAPSHOT_KIND;
+    schemaVersion: number;
+    asOf: EpochMs;
+    conventions: MarketSnapshotConventions;
+    observations: MarketSnapshotObservations;
+    provenance?: Provenance;
+}
+/**
+ * Build an immutable, versioned market snapshot from caller-supplied observations.
+ *
+ * @example
+ * ```ts
+ * import { createMarketSnapshot, marketSnapshotContentHash } from '@insiderfinance/totalfinance/core/artifacts';
+ *
+ * const snapshot = createMarketSnapshot({
+ *   asOf: '2026-07-20T10:30:00-04:00',
+ *   conventions: { dayCount: 'ACT/365F', compounding: 'continuous' },
+ *   observations: {
+ *     spots: { AAPL: { price: 195.3, currency: 'USD' } },
+ *     riskFreeRates: { USD: 0.045 },
+ *     volatilities: { AAPL: 0.24 },
+ *   },
+ *   provenance: { provider: 'insiderfinance', dataset: 'eod', asOf: 1784505600000 },
+ * });
+ * const identity = marketSnapshotContentHash(snapshot); // 'sha256:…'
+ * ```
+ */
+export declare function createMarketSnapshot(input: CreateMarketSnapshotInput): MarketSnapshot;
+/**
+ * The instant of a market snapshot for an OPTION-PRICING consumer. A snapshot created from a bare
+ * date (`asOfConvention: 'date-midnight-utc'`) is refused with the fix: 00:00 UTC is 19:00/20:00 ET
+ * the previous evening, and a same-day option's value depends on the time of day. Ledger consumers
+ * (dated marks) do not call this; they keep the date-granular convention.
+ */
+export declare function requireInstantMarketSnapshot(functionName: string, snapshot: MarketSnapshot): EpochMs;
+/**
+ * Sound structural test for a CURRENT-version market snapshot envelope: the complete read-door
+ * validation (closed keys, kind, version, finite `asOf`, every observation, provenance shape)
+ * behind a boolean door — `true` means `readMarketSnapshot` would accept the value unchanged, with
+ * no migrations. (An earlier version sniffed five fields, so `{ …, asOf: NaN }` and a
+ * conventions-free bag passed as `MarketSnapshot` and detonated downstream.) Full-walk, not
+ * constant-time; when you also need the restored copy, call the read door instead.
+ */
+export declare function isMarketSnapshot(value: unknown): value is MarketSnapshot;
+/**
+ * The ONE door back in for stored snapshots: validates the envelope (closed key set, kind,
+ * version) BEFORE reading any observation, applies explicitly registered migrations for older
+ * versions, refuses newer versions, re-validates the full body, and returns a frozen snapshot
+ * plus the exact migration steps applied (possibly none).
+ */
+export declare function readMarketSnapshot(input: {
+    snapshot: unknown;
+    migrations?: ArtifactMigrationRegistry;
+}): {
+    snapshot: MarketSnapshot;
+    migrationsApplied: AppliedMigration[];
+};
+/**
+ * The snapshot's content identity: `sha256:` over the canonical envelope WITHOUT `provenance`.
+ * Conventions, `asOf`, and every observation are covered (two snapshots that price differently
+ * must never collide); source labels are not (two vendors delivering identical numbers ARE the
+ * same market — dedup and replay comparison depend on that).
+ */
+export declare function marketSnapshotContentHash(snapshot: MarketSnapshot): string;
+//# sourceMappingURL=market-snapshot.d.ts.map

package/modules/core/dist/artifacts/market-snapshot.d.ts.map

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