Core types and errors

Frames, timestamps, calendars, operation descriptors, versions, rolling windows, data-provider contracts and structured errors.

See the usage guide for task-oriented examples. Signatures below are generated from the public headers at the same commit as the rest of this site.

class analysis_context

Lazy, value-owning container for first-phase performance analytics.

summary() returns these stable keys: Annual return, Cumulative returns, Annual volatility, Sharpe ratio, Sortino ratio, Calmar ratio, Max drawdown, Historical value at risk, Conditional value at risk, and, when supplied a benchmark, Alpha and Beta.

Public Functions

explicit analysis_context(dataframe returns, std::optional<dataframe> benchmark = std::nullopt, double annualization = daily_annualization)

Constructs a context from return and optional benchmark frames.

The frames are stored as supplied; only the required double columns are validated, and no sorting or index alignment is performed here.

Parameters:

returns – Frame with a required double returns column.
benchmark – Optional frame with a required double benchmark column; enables the Alpha and Beta summary entries.
annualization – Annualization factor used by annualized metrics.

Throws:

input_error – If a required column is absent, not a double column, or does not match its frame index length.

std::map<std::string, double> summary() const

Returns the cached performance summary.

Core keys are Annual return, Cumulative returns, Annual volatility, Sharpe ratio, Sortino ratio, Calmar ratio, Max drawdown, Historical value at risk and Conditional value at risk. With a benchmark the result also contains Alpha and Beta. Each metric is computed on first use and reused by later calls.

Returns:: Map from stable metric name to computed value.

std::size_t computation_count(std::string_view key) const

Returns how many times key has been computed and cached.

Parameters:: key – Exact summary metric key.
Returns:: Number of computations for key; 0 if it has not been computed.

class batch_fetch_error : public fincore::fincore_error 

Error thrown when a strict batch fetch fails for one or more symbols.

The payload uses category BatchFetchError and code fincore.data.batch_fetch. The message names the provider and the failed symbols in sorted order, and the flat fields hold provider, symbols and error_count.

Public Functions

batch_fetch_error(std::string provider, std::map<std::string, std::string> errors, std::map<std::string, dataframe> partial_results)

Creates a batch fetch error.

Parameters:

provider – Provider name.
errors – Per-symbol error messages.
partial_results – Frames fetched successfully before the failure.

inline const std::string &provider() const noexcept: Returns the provider that produced the failure.

inline const std::map<std::string, std::string> &errors() const noexcept: Returns the per-symbol error messages.

inline const std::map<std::string, dataframe> &partial_results() const noexcept: Returns the frames that were fetched successfully.

class data_provider

Native provider interface for price data.

Live SDK/network subclasses are EXTERNAL_OPTIONAL; the interface, batch orchestration, date validation and return conversion are native and offline-testable with an injected provider.

Public Functions

virtual ~data_provider() = default: Destroys the provider.

virtual std::string provider_name() const = 0

Returns the provider’s stable name.

Returns:: Provider name used in messages and batch errors.

virtual dataframe fetch(std::string_view symbol, std::string_view start, std::string_view end, std::string_view interval = "1d", bool adjust = true) const = 0

Fetches price data for one symbol.

Implementations define how start and end are interpreted; this interface does not validate them. Exceptions derived from std::exception are recorded per symbol by fetch_multiple().

Parameters:

symbol – Instrument identifier.
start – Requested start of the range.
end – Requested end of the range.
interval – Requested interval label; defaults to "1d".
adjust – Price adjustment flag; defaults to true.

Returns:

Fetched price frame.

virtual std::map<std::string, std::string> get_info(std::string_view symbol) const = 0

Returns provider-specific metadata for one symbol.

Parameters:: symbol – Instrument identifier.
Returns:: Key/value metadata for the symbol.

inline virtual bool batch_adjust_default() const

Returns the adjustment flag used when fetch_multiple() is not given one.

Returns:: True by default.

std::map<std::string, dataframe> fetch_multiple(const std::vector<std::string> &symbols, std::string_view start, std::string_view end, std::string_view interval = "1d", std::optional<bool> adjust = std::nullopt, bool strict = false) const

Fetches several symbols through fetch().

The adjustment flag is adjust when supplied, otherwise batch_adjust_default(). Every symbol is attempted. In non-strict mode a failed symbol is stored as an empty frame and its message is discarded; in strict mode the loop still attempts all symbols and then throws if any failed. start and end are passed to fetch() unchanged.

Parameters:

symbols – Instrument identifiers to fetch.
start – Requested start of the range.
end – Requested end of the range.
interval – Requested interval label; defaults to "1d".
adjust – Optional adjustment override.
strict – Whether to throw when any symbol fails.

Throws:

batch_fetch_error – In strict mode when at least one fetch fails; its partial results hold the successful frames.

Returns:

Map from symbol to fetched frame. In non-strict mode failed symbols map to empty frames.

std::vector<double> to_returns(const dataframe &price_data, std::string_view column = "Adj Close") const

Converts a price column to period-over-period simple returns.

column is used when present; otherwise the method falls back to "Close". Consecutive pairs where either price is NaN are skipped. A zero previous price with a nonzero current price yields signed infinity; zero over zero yields NaN and is skipped. Fewer than two prices yield an empty result.

Parameters:

price_data – Frame containing price data.
column – Preferred price column; defaults to "Adj Close".

Throws:

input_error – If the selected column is absent, is not a double column, or does not match the index length. The fallback "Close" is selected only when column is absent.

Returns:

Simple returns in index order.

Public Static Functions

static std::pair<timestamp, timestamp> validate_dates(std::string_view start, std::string_view end)

Parses and validates an ISO-8601 UTC date range.

Accepted forms are YYYY-MM-DD, optionally followed by T or a space and HH:MM:SS with an optional . fraction of up to nine digits. Omitted time components default to midnight. Values are interpreted as UTC; a trailing timezone designator is not accepted.

Parameters:

start – Range start.
end – Range end; must be strictly later than start.

Throws:

fincore_error – With category ValidationError for an unparsable date or when start is not before end.

Returns:

Pair of UTC nanosecond timestamps {start, end}.

class data_snapshot

Immutable, content-addressed snapshot of fetched market data.

The content digest is computed over a canonical native CSV (UTC-nanosecond index plus columns in insertion order); it is a deterministic native provenance digest, not a claim that Python/pandas CSV bytes are identical.

Public Functions

data_snapshot() = default

Creates an empty snapshot.

The timezone defaults to "UTC" and the price adjustment to "raw"; the remaining metadata and the frame are empty.

data_snapshot(std::string provider, std::string requested_start, std::string requested_end, std::string as_of, std::string timezone, std::string price_adjustment, std::string content_sha256, dataframe data)

Creates a snapshot from explicit metadata and data.

Values are stored as supplied; no digest is computed and no consistency check is performed.

Parameters:

provider – Provider name.
requested_start – Requested start date.
requested_end – Requested end date.
as_of – Time at which the data was captured.
timezone – Timezone label.
price_adjustment – Price adjustment label.
content_sha256 – Content digest text.
data – Snapshot frame.

inline dataframe data() const

Returns a defensive copy of the snapshot frame.

Returns:: Copy of the stored frame; later changes to it do not affect the snapshot.

inline const dataframe &stored_data() const noexcept

Returns a reference to the stored frame without copying.

Returns:: Const reference to the snapshot-owned frame.

std::map<std::string, std::string> identity_kwargs() const

Returns the identity metadata of the snapshot.

The map holds provider, requested_start, requested_end, as_of, timezone and price_adjustment; the digest and data are excluded.

Returns:: Map of identity metadata.

std::string to_manifest() const

Returns a JSON manifest describing the snapshot.

The object contains schema_version, provider, requested_start, requested_end, as_of, timezone, price_adjustment and content_sha256; frame data is not included.

Returns:: JSON manifest text.

std::map<std::string, std::string> to_manifest_dict() const

Returns the manifest as a flat string map.

The same fields as to_manifest() are returned, with schema_version rendered as a decimal string.

Returns:: Map of manifest fields.

inline const std::string &provider() const noexcept: Returns the provider name.

inline const std::string &requested_start() const noexcept: Returns the requested start date text.

inline const std::string &requested_end() const noexcept: Returns the requested end date text.

inline const std::string &as_of() const noexcept: Returns the capture time text.

inline const std::string &timezone() const noexcept: Returns the timezone label.

inline const std::string &price_adjustment() const noexcept: Returns the price adjustment label.

inline const std::string &content_sha256() const noexcept: Returns the content digest text.

inline int schema_version() const noexcept

Returns the data snapshot schema version.

Returns:: data_snapshot_schema_version.

Public Static Functions

static data_snapshot from_frame(const dataframe &frame, std::string provider, std::string requested_start, std::string requested_end, std::string as_of, std::string timezone = "UTC", std::string price_adjustment = "raw")

Creates a snapshot and computes its content digest from frame.

A defensive copy of frame is stored, and the digest is dataframe_content_sha256() of that copy.

Parameters:

frame – Frame to snapshot.
provider – Provider name.
requested_start – Requested start date.
requested_end – Requested end date.
as_of – Time at which the data was captured.
timezone – Timezone label; defaults to "UTC".
price_adjustment – Price adjustment label; defaults to "raw".

Throws:

fincore_error – With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.

Returns:

Snapshot with the computed digest and a stored copy of frame.

class fincore_error : public std::runtime_error

Exception type carrying a structured error_info payload.

The std::runtime_error message is the error_info message, so what() returns the same text.

Subclassed by fincore::batch_fetch_error, fincore::research_error

Public Functions

explicit fincore_error(error_info info)

Creates an exception from a structured payload.

Parameters:: info – Error payload to store.

explicit fincore_error(std::string message)

Creates an exception with the default FincoreError category and fincore.error code.

Parameters:: message – Human-readable error message.

inline const error_info &info() const noexcept: Returns the structured error payload.

inline const std::string &category() const noexcept: Returns the source exception class name.

inline const std::string &code() const noexcept: Returns the stable dotted error code.

inline const std::map<std::string, std::string> &fields() const noexcept: Returns the flat error fields.

inline const std::map<std::string, std::string> &report() const noexcept: Returns the diagnostic report entries.

Public Static Functions

static fincore_error from_dict(const std::map<std::string, std::string> &data)

Creates an exception from the flat dictionary form.

Parameters:: data – Flat string map accepted by error_info::from_dict().
Throws:: std::invalid_argument – If error_type is missing or empty.
Returns:: Exception carrying the parsed payload.

class input_error : public std::invalid_argument

Invalid caller input, derived from std::invalid_argument.

The type inherits the std::invalid_argument constructors. Calendar and dataframe helpers such as utc_timestamp() and make_series() throw it for rejected arguments.

class optimization_error : public std::runtime_error

Optimization failure, derived from std::runtime_error.

The type inherits the std::runtime_error constructors. Optimization routines throw it for solver-level failures.

class rolling_engine

Computes trailing-window series for one or more rolling metrics.

The engine owns copies of the return and optional benchmark frames. Each metric is evaluated over every complete window of window observations; rows before the first complete window are omitted from the output.

Public Functions

rolling_engine(dataframe returns, std::optional<dataframe> benchmark = std::nullopt, std::size_t window = static_cast<std::size_t>(daily_annualization), double annualization = daily_annualization)

Constructs an engine over return and optional benchmark frames.

Parameters:

returns – Frame with a required double returns column.
benchmark – Optional frame with a required double benchmark column; required only when rolling beta is requested.
window – Number of observations per window; must be at least 2 and defaults to daily_annualization cast to std::size_t.
annualization – Annualization factor used by annualized metrics.

Throws:

input_error – If window is less than 2, or a required column is absent, not a double column, or does not match its frame index length.

std::map<std::string, dataframe> compute(std::span<const rolling_metric> metrics) const

Returns one trailing-window series per requested metric.

The result maps each metric’s enum name (mean_return, volatility, sharpe, max_drawdown, beta) to a frame whose single returns column holds the metric value at each complete window’s final timestamp. Beta inputs are first aligned on their common index, so its series can be shorter. An empty metric list returns an empty map, and fewer than window available observations yield empty series.

Parameters:: metrics – Metrics to compute.
Throws:: input_error – If a metric value is unknown, beta is requested without a benchmark, or a required column is invalid.
Returns:: Map from metric key to a single-column series indexed by window end timestamps.

struct dependency_status

Availability record for one dependency.

Public Members

std::string name: Dependency name used in error messages.

bool available = false: Whether the dependency is available.

std::string extra: Extra or feature label for the dependency.

struct error_info

Native structured error payload.

Python exception inheritance is not reproduced; the source class name is preserved as category, with a stable code, message, flat fields and an optional diagnostic report.

Public Functions

std::map<std::string, std::string> to_dict() const

Returns the flat dictionary form of this error.

The result starts from fields and adds error_type, message, code when non-empty, and one report.-prefixed key per report entry.

Returns:: Flat string map suitable for error_info::from_dict().

std::string to_json() const

Returns a compact JSON object with category, code, message, fields and report.

String values are JSON-escaped.

Returns:: JSON text.

Public Members

std::string category: Source exception class name, such as ValidationError.

std::string code: Stable dotted error code, such as fincore.validation.

std::string message: Human-readable error message.

std::map<std::string, std::string> fields: Flat string fields such as param_name.

std::map<std::string, std::string> report

Diagnostic report entries; flattened with a report.

prefix by to_dict().

Public Static Functions

static error_info from_dict(const std::map<std::string, std::string> &data)

Builds an error payload from the flat dictionary form.

error_type is required and becomes category. A non-empty code entry overrides the default code formed by prefixing the category with fincore.; a message entry becomes the message; report.-prefixed entries become report entries and all other entries become flat fields.

Parameters:: data – Flat string map, typically produced by to_dict().
Throws:: std::invalid_argument – If error_type is missing or empty.
Returns:: Parsed error payload.

struct operation_descriptor

Stable native operation descriptor.

The pinned Python domains declare an OperationSpec with an operation id, the same capability id, a domain, determinism/RNG policy and provenance. Native consumers need the same stable identity without Python callables, adapters or placeholder implementations. This descriptor therefore carries identity/metadata only; the owning native kernel remains the implementation.

Public Functions

constexpr operation_descriptor() = default

Creates an empty descriptor.

All views are empty, deterministic is true and rng_policy is "none".

inline explicit constexpr operation_descriptor(const std::string_view id, const bool is_deterministic = true, const std::string_view policy = "none") noexcept

Creates a descriptor from an operation id.

capability_id is set to id. domain and provenance_owner are the text before the first dot, or the whole id when it has no dot; source_module is empty when id has no dot, the whole id when it has exactly one dot, and otherwise the text before the second dot.

Parameters:

id – Stable operation identifier.
is_deterministic – Whether the operation is deterministic.
policy – RNG policy label.

Public Members

std::string_view operation_id: Stable operation identifier.

std::string_view capability_id: Capability identifier; defaults to the operation id.

std::string_view domain: Domain portion of the operation id.

std::string_view source_module: Module portion of the operation id.

std::string_view provenance_owner: Provenance owner; defaults to the domain.

bool deterministic = {true}: Whether the operation is deterministic.

std::string_view rng_policy = {"none"}: RNG policy label.

struct request_policy

Bounded, deterministic retry policy for external data access.

Mirrors the pinned fincore.data.contracts.RequestPolicy predicates without importing a network stack.

Public Functions

request_policy() = default: Creates a policy with the default values.

request_policy(double connect_timeout, double read_timeout, double total_timeout, int max_attempts)

Creates a policy and validates its values.

Parameters:

connect_timeout – Connect timeout value.
read_timeout – Read timeout value.
total_timeout – Total timeout value.
max_attempts – Maximum attempt count.

Throws:

fincore_error – With category ValidationError when a timeout is not positive or max_attempts is less than 1.

void validate() const

Validates the timeout and attempt values.

Throws:: fincore_error – With category ValidationError when a timeout is not positive or max_attempts is less than 1.

bool should_retry(transport_error_kind kind) const noexcept

Returns whether failures of kind are retried.

Connection, timeout and operating-system failures are retryable; validation, none and other are not.

Parameters:: kind – Transport failure classification.
Returns:: True for retryable kinds.

int remaining_attempts(int attempt) const noexcept

Returns the attempts left after attempt.

The result is max_attempts - attempt, clamped to zero.

Parameters:: attempt – One-based attempt number.
Returns:: Remaining attempts, never negative.

Public Members

double connect_timeout = 10.0: Connect timeout; defaults to 10.0.

double read_timeout = 30.0: Read timeout; defaults to 30.0.

double total_timeout = 60.0: Total timeout; defaults to 60.0.

int max_attempts = 3: Maximum attempt count; defaults to 3.

enum class fincore::rolling_metric

Trailing-window metric computed by rolling_engine.

Values:

enumerator mean_return: Annualized arithmetic mean of the window.

enumerator volatility: Annualized sample volatility of the window.

enumerator sharpe: Annualized Sharpe ratio with zero risk-free rate.

enumerator max_drawdown: Worst peak-to-trough drawdown in the window.

enumerator beta: Unannualized beta against the aligned benchmark window.

enum class fincore::transport_error_kind

Classification of a transport failure for retry decisions.

Values:

enumerator none: No transport error.

enumerator connection: Connection-level failure; retryable.

enumerator timeout: Request timeout; retryable.

enumerator operating_system: Operating-system transport failure; retryable.

enumerator validation: Request validation failure; not retried.

enumerator other: Any other failure; not retried.

std::pair<dataframe, dataframe> fincore::align_on_common_index(const dataframe &left, std::string_view left_column, const dataframe &right, std::string_view right_column)

Returns two single-column frames restricted to their common timestamps.

The result is an inner join on the timestamp index. Timestamps are taken from left in its existing order, and values are matched against right by timestamp; timestamps present in only one input are dropped.

Parameters:

left – Frame supplying the aligned timestamps and the left column.
left_column – Double column to keep from left.
right – Frame supplying the right-hand values.
right_column – Double column to keep from right.

Throws:

input_error – If either column is missing, is not a double column, or does not match its frame index length.

Returns:

Pair of frames with identical indexes holding the left and right values for the common timestamps.

error_info fincore::alignment_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns an AlignmentError payload via contextual_error().

Parameters:

message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Alignment error payload with code fincore.contract.

std::span<const operation_descriptor> fincore::all_operations()

Returns all declared operations in domain order.

Returns:: View of static storage ordered by attribution, optimization, performance, portfolio, report, risk, simulation, data, factor analysis and metrics. The view is stable for the process lifetime.

std::span<const operation_descriptor> fincore::attribution_operations()

Returns the attribution operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::string fincore::canonical_dataframe_csv(const dataframe &frame)

Returns a canonical CSV rendering of frame.

The first line is index followed by the column names in insertion order; each subsequent line holds the UTC-nanosecond index value and the column values. Doubles use Python-compatible float formatting, except that NaN is an empty field and infinities are inf or -inf; booleans are True or False; strings are quoted only when needed, with embedded quotes doubled. Integral columns are rendered as decimal integers. The output ends with a newline.

Parameters:: frame – Frame to render.
Throws:: fincore_error – With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.
Returns:: CSV text.

void fincore::check_dependencies(std::span<const dependency_status> dependencies)

Throws when any listed dependency is unavailable.

The error is a DependencyError whose dependency field lists every unavailable name in input order, joined with ", ". The extra field is the first non-empty extra label among the unavailable dependencies and is omitted when none supplies one. Its message is Missing required dependencies: followed by the names.

Parameters:: dependencies – Dependency records to check.
Throws:: fincore_error – With category DependencyError when at least one entry is unavailable.

error_info fincore::contextual_error(std::string category, std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns an error payload with operation context and code fincore.contract.

category is used verbatim. Optional context values are stored in fields under operation_id, parameter, path and profile only when non-empty.

Parameters:

category – Source exception class name.
message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Contextual error payload.

error_info fincore::data_alignment_error(std::string message, std::optional<std::int64_t> returns_length = std::nullopt, std::optional<std::int64_t> factor_length = std::nullopt)

Returns a DataAlignmentError payload with code fincore.data_alignment.

Optional lengths are stored as decimal strings under returns_length and factor_length.

Parameters:

message – Human-readable error message.
returns_length – Number of return observations, if known.
factor_length – Number of factor observations, if known.

Returns:

Data-alignment error payload.

std::span<const operation_descriptor> fincore::data_operations()

Returns the data operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::string fincore::dataframe_content_sha256(const dataframe &frame)

Returns the lowercase hexadecimal SHA-256 of canonical_dataframe_csv().

Parameters:: frame – Frame to digest.
Throws:: fincore_error – With category UnsupportedFormatError when the frame cannot be encoded as canonical CSV.
Returns:: 64-character lowercase hexadecimal digest.

error_info fincore::dependency_error(std::string message, std::string dependency = {}, std::string extra = {})

Returns a DependencyError payload with code fincore.dependency.

dependency and extra are stored in fields only when non-empty.

Parameters:

message – Human-readable error message.
dependency – Missing dependency name, if known.
extra – Extra or feature label associated with the dependency.

Returns:

Dependency error payload.

double fincore::ensure_not_nan(double value, std::string_view param_name, std::optional<double> replace_with = std::nullopt)

Returns value, or replace_with when value is NaN.

Parameters:

value – Value to check.
param_name – Parameter name used in the error message and field.
replace_with – Replacement used instead of throwing, if supplied.

Throws:

fincore_error – When value is NaN and replace_with is absent; the payload is a ValidationError for param_name.

Returns:

value when it is not NaN, otherwise the supplied replacement.

std::span<const operation_descriptor> fincore::factor_analysis_operations()

Returns the factor analysis operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

template<typename Function> decltype(auto) fincore::handle_numerical_error(std::string_view operation, Function &&function)

Runs a numeric kernel and converts native numeric exceptions to NumericalError.

Existing fincore_error exceptions pass through unchanged. std::domain_error, std::overflow_error, std::underflow_error, std::invalid_argument and other std::runtime_error exceptions are rethrown as fincore_error payloads from numerical_error() with the supplied operation label. The kernel result is returned unchanged.

Template Parameters:

Function – Callable type invoked with no arguments.

Parameters:

operation – Numeric operation label stored in the error payload.
function – Kernel to invoke.

Throws:

fincore_error – For the converted native exceptions.

Returns:

Whatever function() returns.

error_info fincore::input_contract_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns an InputContractError payload via contextual_error().

Parameters:

message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Input-contract error payload with code fincore.contract.

error_info fincore::insufficient_data_error(std::string message, std::optional<std::int64_t> required_length = std::nullopt, std::optional<std::int64_t> actual_length = std::nullopt)

Returns an InsufficientDataError payload with code fincore.insufficient_data.

Optional lengths are stored as decimal strings under required_length and actual_length.

Parameters:

message – Human-readable error message.
required_length – Minimum required observation count, if known.
actual_length – Observed count, if known.

Returns:

Insufficient-data error payload.

error_info fincore::invalid_period_error(std::string period)

Returns an InvalidPeriodError payload for period.

The payload uses code fincore.invalid_period, lists the accepted periods (daily, weekly, monthly, quarterly, yearly) and stores period and valid_periods in fields.

Parameters:: period – Rejected period label.
Returns:: Invalid-period error payload.

error_info fincore::make_error(std::string category, std::string code, std::string message, std::map<std::string, std::string> fields = {}, std::map<std::string, std::string> report = {})

Returns a structured error payload built from the supplied components.

No validation or normalization is applied; fields and report are stored as given.

Parameters:

category – Source exception class name.
code – Stable dotted error code.
message – Human-readable error message.
fields – Flat string fields.
report – Diagnostic report entries.

Returns:

Error payload with the supplied values.

error_info fincore::make_operation_resolution_error(std::string operation_id)

Returns a runtime diagnostic error for an unknown operation identifier.

The payload uses category RuntimeDiagnosticError, code fincore.runtime.operation_resolution, runtime category resolution_failure, an unknown operation_id: message followed by the identifier, and a remediation that points at the operation catalog.

Parameters:: operation_id – Unknown operation identifier.
Returns:: Runtime diagnostic payload for the resolution failure.

dataframe fincore::make_series(std::vector<timestamp> index, std::string_view column_name, std::vector<double> values)

Returns a single-column frame built from an index and double values.

The column is loaded without NaN padding, so the index and column sizes remain equal to the input sizes.

Parameters:

index – Timestamps for the rows, in the caller’s order.
column_name – Name of the double column; must not be empty.
values – Values parallel to index.

Throws:

input_error – If column_name is empty or the two input vectors have different sizes.

Returns:

Frame whose index is index and whose only column is column_name.

std::span<const operation_descriptor> fincore::metrics_operations()

Returns the metrics operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::missing_data_error(std::string message, std::string missing_field = {})

Returns a MissingDataError payload with code fincore.missing_data.

missing_field is stored in fields only when non-empty.

Parameters:

message – Human-readable error message.
missing_field – Name of the missing field, if known.

Returns:

Missing-data error payload.

error_info fincore::numerical_convergence_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns a NumericalConvergenceError payload via contextual_error().

Parameters:

message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Numerical-convergence error payload with code fincore.contract.

error_info fincore::numerical_error(std::string message, std::string operation = {})

Returns a NumericalError payload with code fincore.numerical.

operation is stored in fields only when non-empty.

Parameters:

message – Human-readable error message.
operation – Numeric operation label, if known.

Returns:

Numerical error payload.

std::span<const operation_descriptor> fincore::optimization_operations()

Returns the optimization operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::performance_operations()

Returns the performance operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::portfolio_operations()

Returns the portfolio operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::span<const operation_descriptor> fincore::report_operations()

Returns the report operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

std::span<const double> fincore::require_double_column(const dataframe &frame, std::string_view column_name)

Returns a view of the named double column in frame.

Parameters:

frame – Frame to inspect.
column_name – Name of the required double column.

Throws:

input_error – If column_name is empty, the column is absent, the column is not of type double, or its size differs from the index size.

Returns:

View over the column values; it references the frame’s storage.

error_info fincore::resource_lifecycle_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns a ResourceLifecycleError payload via contextual_error().

Parameters:

message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Resource-lifecycle error payload with code fincore.contract.

error_info fincore::result_contract_error(std::string message, std::string operation_id = {}, std::string parameter = {}, std::string path = {}, std::string profile = {})

Returns a ResultContractError payload via contextual_error().

Parameters:

message – Human-readable error message.
operation_id – Operation identifier, if known.
parameter – Parameter name, if known.
path – Artifact path, if known.
profile – Profile name, if known.

Returns:

Result-contract error payload with code fincore.contract.

std::span<const operation_descriptor> fincore::risk_operations()

Returns the risk operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::runtime_diagnostic_error(std::string message, std::string runtime_category, std::string operation_id = {}, std::string capability_id = {}, std::map<std::string, std::string> details = {}, std::string remediation = {})

Returns a RuntimeDiagnosticError payload with code fincore.runtime.diagnostic.

runtime_category is always stored in fields; operation_id, capability_id and remediation are stored only when non-empty. details becomes the diagnostic report.

Parameters:

message – Human-readable error message.
runtime_category – Runtime classification, such as resolution_failure.
operation_id – Operation identifier, if known.
capability_id – Capability identifier, if known.
details – Diagnostic report entries.
remediation – Suggested remediation text, if known.

Returns:

Runtime diagnostic payload.

double fincore::safe_divide(double numerator, double denominator, double default_value = std::numeric_limits<double>::quiet_NaN())

Returns numerator / denominator, or default_value when the denominator is zero.

Parameters:

numerator – Dividend.
denominator – Divisor; zero selects default_value.
default_value – Value returned for a zero denominator; defaults to NaN.

Returns:

Quotient, or default_value for a zero denominator.

double fincore::safe_sqrt(double value, double default_value = std::numeric_limits<double>::quiet_NaN())

Returns the square root of value, or default_value when value is negative.

Parameters:

value – Input value.
default_value – Value returned for a negative input; defaults to NaN.

Returns:

Square root, or default_value when value < 0.

std::span<const operation_descriptor> fincore::simulation_operations()

Returns the simulation operations in source order.

Returns:: View of static descriptor storage; valid for the process lifetime.

error_info fincore::unsupported_format_error(std::string message, std::string format = {})

Returns an UnsupportedFormatError payload with code fincore.unsupported_format.

format is stored in fields only when non-empty.

Parameters:

message – Human-readable error message.
format – Rejected format label, if known.

Returns:

Unsupported-format error payload.

timestamp fincore::utc_timestamp(int year, unsigned month = 1, unsigned day = 1, unsigned hour = 0, unsigned minute = 0, unsigned second = 0, unsigned nanosecond = 0)

Returns the UTC Unix-epoch timestamp for a calendar date and time.

Components are interpreted in UTC. The month and day default to January 1, and the time components default to midnight. Sub-second precision is carried in nanoseconds.

Parameters:

year – Calendar year supported by std::chrono::year.
month – Month in [1, 12]; defaults to January.
day – Day of month in [1, 31]; defaults to 1.
hour – Hour in [0, 23]; defaults to 0.
minute – Minute in [0, 59]; defaults to 0.
second – Second in [0, 59]; defaults to 0.
nanosecond – Nanosecond in [0, 999999999]; defaults to 0.

Throws:

input_error – If a component is out of range, the calendar date does not exist, or the timestamp is outside the representable int64 range.

Returns:

Signed nanoseconds since 1970-01-01T00:00:00Z.

int fincore::utc_year(timestamp value) noexcept

Returns the UTC calendar year containing value.

Parameters:: value – Signed nanosecond timestamp since the Unix epoch.
Returns:: UTC calendar year, including years before 1970.

error_info fincore::validation_error(std::string message, std::string param_name = {}, std::string value = {})

Returns a ValidationError payload with code fincore.validation.

param_name and value are stored in fields only when non-empty.

Parameters:

message – Human-readable error message.
param_name – Offending parameter name, if known.
value – Rejected value rendered as text, if known.

Returns:

Validation error payload.

std::string_view fincore::version() noexcept

Returns the pinned oracle version as an owning-friendly view.

Returns:: View of pinned_version_string, valid for the process lifetime.

using fincore::dataframe = hmdf::StdDataFrame<timestamp>: Columnar frame indexed by timestamp, backed by hmdf::StdDataFrame.

using fincore::timestamp = std::int64_t: Signed timestamp in UTC nanoseconds since the Unix epoch.

constexpr int fincore::data_snapshot_schema_version = 1: Schema version written into data snapshot manifests.

constexpr int fincore::pinned_version_major = 0

Pinned Python oracle identity (fincore.__version__ at 3e9ef205ef2023f92e89fddd1052d46b16429c64).

Pinned major version.

constexpr int fincore::pinned_version_minor = 5: Pinned minor version.

constexpr int fincore::pinned_version_patch = 2: Pinned patch version.

constexpr const char *fincore::pinned_version_string = "0.5.2.dev0": Pinned oracle version text.

constexpr int fincore::version_major = 0

Native library version retained from the current C4 base.

The pinned Python oracle version is exposed separately below so installed-consumer metadata checks can compare against the frozen Python pin without pretending the native ABI version changed. Native major version.

constexpr int fincore::version_minor = 1: Native minor version.

constexpr int fincore::version_patch = 0: Native patch version.

constexpr const char *fincore::version_string = "0.1.0": Native version.