Runtime

Operation catalogs, sessions, snapshots, artifact bundles and serialization helpers.

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_session

Caches deterministic results for one catalog across a session lifecycle.

Public Functions

explicit analysis_session(const operation_catalog &catalog)

Creates an open session that owns a copy of catalog.

inline bool closed() const noexcept

Returns whether close() has sealed the session.

inline std::size_t cache_entries() const noexcept

Returns the number of cached results.

inline const std::string &catalog_digest() const noexcept

Returns the digest of the owned catalog snapshot.

runtime_result run(const std::string &operation_id, const runtime_inputs &inputs, const runtime_config &config = {})

Runs an operation, reusing cached results for deterministic operations.

Deterministic cache hits and misses set metadata["cache"] to hit and miss; nondeterministic results are returned without caching. Throws std::runtime_error when the session is closed and operation_resolution_error for an unknown operation.

void clear()

Clears entries without changing whether the session is open or closed.

void close() noexcept

Clears the cache and seals the session against further runs.

class analysis_snapshot

Owning snapshot of runtime inputs with a stable input digest.

Public Functions

analysis_snapshot() = default

Constructs an empty snapshot with the digest of an empty input map.

explicit analysis_snapshot(runtime_inputs inputs)

Creates a snapshot that owns inputs and computes its digest.

inline const runtime_inputs &materialize() const

Returns the owned inputs.

inline const std::string &digest() const

Returns the digest of the owned inputs.

class native_backend

Native generic dense-array operations corresponding to the pinned NumPy backend.

Inputs are copied and validated at each public boundary.

Public Functions

dense_array as_float_array(const dense_array &value, std::string_view name = "value", std::optional<std::int64_t> ndim = std::nullopt) const

Returns a validated owning copy of value as a dense double array.

Throws input_error when the shape is empty or inconsistent with the value count, the dimension does not match ndim, the size is below one, or any value is non-finite.

template<typename T>
inline dense_array as_float_array(const std::vector<T> &value, std::string_view name = "value", std::optional<std::int64_t> ndim = std::nullopt) const

Converts an arithmetic vector and delegates to the dense-array overload.

dense_array cumulative_product(const dense_array &value) const

Returns the running cumulative product of a one-dimensional array.

The result has the same shape as the validated input. Throws input_error when the input fails as_float_array validation.

double sample_standard_deviation(const dense_array &value) const

Returns the sample standard deviation using Bessel’s correction.

Throws input_error when the input is invalid or holds fewer than two values.

template<typename T>
inline dense_array cumulative_product(const std::vector<T> &value) const

Converts an arithmetic vector and returns its cumulative product.

template<typename T>
inline double sample_standard_deviation(const std::vector<T> &value) const

Converts an arithmetic vector and returns its sample standard deviation.

Public Static Attributes

static constexpr std::string_view name = {"native"}

Backend name reported to callers.

class operation_catalog

Ordered, digest-addressed set of validated operation declarations.

Public Functions

explicit operation_catalog(std::vector<operation_spec> operations, std::optional<std::string> extension_digest = std::nullopt)

Creates a catalog from operations, optionally binding an extension digest.

Declarations are sorted by operation_id. Throws input_error for empty identifiers or RNG policies, a missing callable, duplicate operation identifiers, unpaired semantic modes, or repeated modes on one capability.

inline const std::vector<operation_spec> &operations() const

Returns all declarations sorted by operation identifier.

inline const std::string &digest() const

Returns the SHA-256 digest of the canonical catalog payload.

const operation_spec &resolve(const std::string &operation_id) const

Returns the declaration for operation_id.

Throws operation_resolution_error when the identifier is unknown.

std::vector<std::string> operation_ids() const

Returns operation identifiers in catalog order.

inline const std::optional<extensions::extension_snapshot> &extension_snapshot() const noexcept

Returns the pinned extension snapshot, or nullopt when unbound.

This mirrors the source property that returns None for a catalog without extension bindings.

operation_catalog with_extensions(const extensions::extension_snapshot &snapshot, const std::map<std::string, std::function<runtime_value(const runtime_inputs&)>> &callables) const

Returns a new catalog with one immutable extension snapshot bound.

The caller supplies native callables because the extension ABI carries metadata, not callables; a missing callable is a contract error, never a placeholder. Throws input_error when a callable is missing, this catalog is already bound, or merged declarations are invalid.

class operation_resolution_error : public std::runtime_error

Reports that a catalog lookup found no matching operation identifier.

Public Functions

inline explicit operation_resolution_error(const std::string &operation_id)

Constructs the error with a message naming operation_id.

struct artifact_bundle

Owning collection of named artifact bytes and their descriptors.

Public Functions

void add(std::string name, std::string bytes, artifact_descriptor descriptor = {})

Registers one artifact and its descriptor.

Throws fincore_error when the bundle is closed and a validation fincore_error for an empty or duplicate artifact name.

inline void close() noexcept

Seals the bundle against further registration; repeat calls are safe.

inline bool closed() const noexcept

Returns whether the bundle has been sealed.

Public Members

std::map<std::string, std::string> artifacts

Artifact bytes keyed by exact artifact path.

std::map<std::string, std::string> metadata

Bundle-level metadata preserved in the manifest.

std::map<std::string, artifact_descriptor> descriptors

Optional per-artifact metadata keyed by the exact artifact path.

Every descriptor key must name an entry in artifacts. The manifest records the media type, byte length, SHA-256 of the actual artifact bytes, and provenance for each artifact; omitted descriptors use the legacy octet-stream/empty-provenance defaults.

bool is_closed = false

Native lifecycle seal set by close().

Artifacts are owning byte strings, so closing has no external resources to release; it prevents further registration.

struct artifact_descriptor

Describes the media type and provenance of one artifact.

Public Members

std::string media_type = "application/octet-stream"

MIME type used by consumers of this artifact.

Legacy artifacts without an explicit descriptor are recorded as application/octet-stream.

std::map<std::string, std::string> provenance

Artifact-specific provenance metadata.

struct dense_array

Dense row-major numeric storage with explicit dimensions.

Public Members

std::vector<double> values

Flat row-major values.

std::vector<std::size_t> shape

Dimension sizes.

struct execution_plan

Resolved batch of requests tied to the digest of one catalog snapshot.

Public Members

std::string catalog_digest

Digest of the catalog the plan was resolved against.

std::vector<operation_request> requests

Requests in caller-supplied order.

struct operation_request

Snapshot of one operation request with digests of its inputs and config.

Public Functions

operation_request(std::string operation_id, runtime_inputs inputs, runtime_config config = {})

Creates a request and computes both request digests.

Throws input_error when operation_id is empty or when an input or config key is empty.

Public Members

std::string operation_id

Requested operation identifier.

runtime_inputs inputs

Inputs forwarded to the operation callable.

runtime_config config

Recorded configuration; never forwarded to the callable.

std::string input_digest

Digest over inputs, computed by the constructor.

std::string config_digest

Digest over config, computed by the constructor.

struct operation_spec

Declaration of one catalog operation and its native callable.

Public Functions

std::string implementation_fingerprint() const

Returns the stable native implementation identity.

The declared kernel_symbol provenance value wins when present (the native analogue of Python module:qualname); otherwise the identity is domain:capability_id.

Public Members

std::string operation_id

Unique catalog identifier.

std::string capability_id

Leaf capability identifier shared by mode variants.

std::string domain

Source domain, such as metrics or report.

std::function<runtime_value(const runtime_inputs&)> callable

Native function invoked with validated runtime inputs.

bool deterministic = true

Whether the operation result may be cached by an analysis session.

std::string rng_policy = "none"

Random-state policy; none for deterministic kernels.

std::optional<std::string> semantic_mode

Optional semantic mode distinguishing variants of one capability.

std::optional<std::string> mode_approval

Optional approval token that must accompany semantic_mode.

std::map<std::string, std::string> provenance

Free-form provenance metadata such as owner and kernel symbol.

struct runtime_result

Operation value plus string metadata describing the run.

Public Members

runtime_value value

Value returned by the operation callable.

std::map<std::string, std::string> metadata

Run metadata such as operation, input and catalog digests.

struct runtime_result_payload

Owning, versioned representation of a runtime result.

Copies own their DataFrame buffers and all nested report/risk values.

Public Members

int schema_version = runtime_result_schema_version

Payload schema version.

runtime_value value

Result value.

std::map<std::string, std::string> metadata

Result metadata.

struct runtime_value

Owning dynamically typed value passed through the runtime layer.

Public Types

using storage = std::variant<std::monostate, bool, std::int64_t, double, std::string, dataframe, report_document, risk_model_spec, walk_forward_var_result, risk_validation_report, std::vector<portfolio_transaction>>

Supported alternatives; std::monostate represents a null value.

Public Functions

runtime_value() = default

Constructs a null value.

inline runtime_value(bool value)

Constructs a boolean value.

inline runtime_value(int value)

Constructs a 64-bit integer value from value.

inline runtime_value(std::int64_t value)

Constructs a 64-bit integer value.

inline runtime_value(double value)

Constructs a double value.

inline runtime_value(std::string value)

Constructs a string value.

inline runtime_value(dataframe value)

Constructs a dataframe value.

inline runtime_value(report_document value)

Constructs a report document value.

inline runtime_value(risk_model_spec value)

Constructs a risk model specification value.

inline runtime_value(walk_forward_var_result value)

Constructs a walk-forward VaR result value.

inline runtime_value(risk_validation_report value)

Constructs a risk validation report value.

inline runtime_value(std::vector<portfolio_transaction> value)

Constructs a portfolio transaction list value.

Public Members

storage data

Active stored alternative.

enum class fincore::alignment_policy

Time-series index alignment strategy.

Values:

enumerator strict

Requires identical indices in every frame.

enumerator inner

Keeps labels present in every frame.

enumerator outer_dropna

Keeps labels complete across all frames, dropping gaps.

std::pair<dataframe, dataframe> fincore::align_binary_metric_inputs(const dataframe &left, const dataframe &right, alignment_policy policy = alignment_policy::inner)

Aligns two labelled frames under the same policy as align_time_series.

Throws input_error for the same invalid inputs as align_time_series.

std::pair<dense_array, dense_array> fincore::align_binary_metric_inputs(const dense_array &left, const dense_array &right, alignment_policy policy = alignment_policy::inner)

Aligns positional arrays by first-axis length.

This overload deliberately cannot accept a labelled frame on either side. The arrays are returned unchanged after validation; throws input_error for an unknown policy, an inconsistent shape, or unequal first-axis lengths.

std::vector<dataframe> fincore::align_time_series(const std::vector<dataframe> &values, alignment_policy policy)

Aligns double-column frames by their UTC-nanosecond index.

All column names and order are retained. Unsupported column types and duplicate indices are rejected. Non-double columns are not coerced. Throws input_error when the policy is unknown or strict alignment finds different indices.

std::vector<operation_spec> fincore::attribution_factor_operations()

Native-compatible runtime operations for the Iteration 8 P105 domains: attribution, factor_analysis, optimization, report.factor and the native data-snapshot model.

Every declaration maps an exact source operation id to an existing native kernel. Composite native results are projected onto an owning report_document; tabular kernels return an owning dataframe. rng_policy is none and every operation is deterministic.

std::vector<runtime_result> fincore::batch(const execution_plan &plan, const operation_catalog &catalog)

Runs every request in plan against the catalog that produced it.

Results are returned in request order. Throws input_error when the plan digest does not match catalog, and propagates per-request validation errors.

operation_catalog fincore::builtin_catalog()

Returns the builtin catalog of native metrics, risk and report operations.

Builtin report operation inputs follow the pinned source IDs. The walk-forward operation requires returns (dataframe) and spec (risk_model_spec). Risk validation requires result (walk_forward_var_result) and accepts optional index_name (string). Risk document construction requires report (risk_validation_report) and accepts optional title (string). Portfolio report construction requires returns (dataframe) and accepts optional benchmark, positions (dataframe), transactions (vector<portfolio_transaction>), rolling_window (integer), and title (string). These operations ignore config values and do not forward them to domain functions.

runtime_result fincore::copy_for_consumer(const runtime_result &result)

Returns an owning value-semantic copy of a runtime result.

runtime_result fincore::from_json(std::string_view json)

Parses a JSON envelope into a runtime result.

Throws input_error for malformed JSON, duplicate object keys, invalid UTF-8, unsupported schema versions, or out-of-range numbers.

runtime_result fincore::from_payload(const runtime_result_payload &payload)

Validates a payload and returns an owning runtime result.

Supported values and nested shapes are checked. Throws input_error for an unsupported schema version or an invalid value representation.

void fincore::load_optional_module(std::string_view module_name, bool available, std::string_view dependency = {}, std::string_view extra = {}, std::string_view message = {})

Checks a native capability dependency and throws when it is unavailable.

Native callers declare availability explicitly instead of importing an optional Python module; an unavailable capability raises a structured DependencyError. An empty dependency defaults to module_name, and an empty message is replaced by an optional_dependency_missing message.

operations_provider fincore::make_operations_provider(std::vector<operation_spec> declarations)

Creates a provider that captures and returns the supplied declarations.

std::vector<operation_spec> fincore::metrics_performance_operations()

Native runtime declarations for the metrics.

* and performance.* operation domains that are not already part of builtin_catalog().

Every declaration maps to an existing native kernel. The declarations are deterministic and consume no random state (rng_policy == "none").

dataframe fincore::normalize_time_series_timezone(const dataframe &value, std::string_view normalize_tz)

Returns a UTC-normalized copy of a time-series frame.

Native timestamps are UTC nanoseconds. “UTC” normalization therefore returns an owning copy; named-zone conversion is outside this API. Throws input_error when normalize_tz is not UTC, compared case-insensitively.

execution_plan fincore::plan(const std::vector<operation_request> &requests, const operation_catalog &catalog)

Validates every request against catalog and records its digest.

Throws operation_resolution_error for an unknown operation identifier.

std::vector<operation_spec> fincore::portfolio_risk_simulation_operations()

Native-compatible runtime operations for the portfolio, risk and simulation source domains (Iteration 8 / P105).

The returned declarations preserve the authoritative operation IDs from the reconciliation catalog. Every callable invokes an existing native kernel; structured results that have no dedicated runtime_value alternative are serialized into a dataframe with the schema documented in the operation’s provenance["input_schema"] entry.

runtime_result fincore::run(const std::string &operation_id, const runtime_inputs &inputs, const runtime_config &config, const operation_catalog &catalog)

Runs one operation and returns its value with run metadata.

Config is recorded in result metadata only; operation callables receive runtime inputs and never receive config.

Throws operation_resolution_error when the operation is unknown and propagates validation errors raised by the callable.

std::string fincore::runtime_value_digest(const runtime_value &value)

Returns a deterministic SHA-256 digest of value.

DataFrame digests include index values, column names, types and contents for bool, character, integral, float, double and std::string columns. Other column types are rejected so session cache keys never omit input data. Throws input_error for an unsupported dataframe column type.

std::string fincore::semantic_digest(const runtime_result &result)

Returns a versioned semantic digest of a runtime result.

The digest is SHA-256 over the canonical native payload, domain-separated and versioned. Volatile metadata such as run durations, run identifiers and path-valued keys is excluded so equivalent results compare equal.

std::string fincore::to_json(const runtime_result &result)

Serializes a runtime result to deterministic JSON.

The JSON envelope is deterministic for a given native runtime_result. Numeric values use explicit tags so non-finite values and signed zero survive. Throws input_error for values that cannot be represented.

runtime_result_payload fincore::to_payload(const runtime_result &result)

Converts a runtime result into an owning versioned payload.

dense_array fincore::validate_finite_array(const dense_array &value, std::string_view name = "value", std::int64_t min_size = 1, std::optional<std::int64_t> ndim = std::nullopt)

Return an owning copy after checking shape, size and finite-value rules.

template<typename T, typename Compare, typename Allocator>
std::map<std::string, T, Compare, Allocator> fincore::validate_mapping(const std::map<std::string, T, Compare, Allocator> &value, std::string_view name)

Return a copy of a typed string-keyed mapping after rejecting empty keys.

runtime_result fincore::with_metadata(const runtime_result &result, const std::map<std::string, std::string> &metadata)

Returns a copy with the supplied metadata keys overwritten.

Keys present in metadata replace existing values; all other metadata from result is retained.

void fincore::write_artifact_bundle(const artifact_bundle &bundle, const std::filesystem::path &output_directory)

Writes a bundle into a new output directory.

Existing output directories, unsafe artifact paths and symlink parents are rejected. The bundle metadata and artifact names are preserved in .fincore-manifest.json; per-file descriptors are validated before any output is created. Throws fincore_error for a closed bundle and input_error for rejected paths or descriptors.

using fincore::operations_provider = std::function<std::vector<operation_spec>()>

Factory that returns a copy of a fixed set of operation declarations.

using fincore::runtime_config = std::map<std::string, runtime_value>

Named runtime configuration keyed by non-empty config name.

using fincore::runtime_inputs = std::map<std::string, runtime_value>

Named runtime inputs keyed by non-empty input name.

constexpr int fincore::runtime_result_schema_version = 1

Current runtime result payload schema version.