运行时

操作目录、会话、快照、产物包和序列化辅助工具。

面向任务的使用示例请参阅使用指南。以下签名与本站其余内容在同一提交中由公共头文件生成。

class analysis_session

在一个会话生命周期内为一个目录缓存确定性结果。

公共函数

explicit analysis_session(const operation_catalog &catalog)

创建一个打开状态的会话，该会话持有 catalog 的副本。

inline bool closed() const noexcept

返回 close() 是否已封闭会话。

inline std::size_t cache_entries() const noexcept

返回已缓存结果的数量。

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

返回所持有目录快照的摘要。

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

运行操作，对确定性操作复用缓存结果。

确定性缓存命中与未命中会将 metadata["cache"] 设为 hit 和 miss；非确定性结果直接返回而不缓存。会话已关闭时抛出 std::runtime_error，操作未知时抛出 operation_resolution_error。

void clear()

清空条目，但不改变会话处于打开还是关闭状态。

void close() noexcept

清空缓存并封闭会话，禁止后续运行。

class analysis_snapshot

持有运行时输入的快照，带有稳定的输入摘要。

公共函数

analysis_snapshot() = default

构造空快照，其摘要为空输入映射的摘要。

explicit analysis_snapshot(runtime_inputs inputs)

创建持有 inputs 并计算其摘要的快照。

inline const runtime_inputs &materialize() const

返回所持有的输入。

inline const std::string &digest() const

返回所持有输入的摘要。

class native_backend

与锁定 NumPy 后端对应的原生通用稠密数组操作。

输入在每个公共边界处被复制并校验。

公共函数

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

返回 value 作为稠密 double 数组的、经校验的持有副本。

当形状为空或与值数量不一致、维度与 ndim 不匹配、大小小于一，或任一值非有限时，抛出 input_error。

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

转换算术向量并委托给稠密数组重载。

dense_array cumulative_product(const dense_array &value) const

返回一维数组的运行累积乘积。

结果与经校验的输入形状相同。输入未通过 as_float_array 校验时抛出 input_error。

double sample_standard_deviation(const dense_array &value) const

使用贝塞尔校正返回样本标准差。

输入无效或包含少于两个值时抛出 input_error。

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

转换算术向量并返回其累积乘积。

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

转换算术向量并返回其样本标准差。

公共静态属性

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

向调用方报告的后端名称。

class operation_catalog

有序、按摘要寻址的已校验操作声明集合。

公共函数

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

根据 operations 创建目录，可选绑定扩展摘要。

声明按 operation_id 排序。当标识符或 RNG 策略为空、缺少可调用对象、操作标识符重复、语义模式未成对，或同一能力上重复出现模式时，抛出 input_error。

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

返回按操作标识符排序的所有声明。

inline const std::string &digest() const

返回规范目录负载的 SHA-256 摘要。

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

返回 operation_id 对应的声明。

标识符未知时抛出 operation_resolution_error。

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

按目录顺序返回操作标识符。

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

返回锁定的扩展快照；未绑定时返回 nullopt。

这对应源实现中无扩展绑定的目录返回 None 的属性。

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

返回绑定了单个不可变扩展快照的新目录。

由于扩展 ABI 只携带元数据而不携带可调用对象，调用方需提供原生可调用对象；缺少可调用对象属于约定错误，绝不会使用占位实现。当可调用对象缺失、此目录已绑定，或合并后的声明无效时，抛出 input_error。

class operation_resolution_error : public std::runtime_error

表示目录查找未找到匹配的操作标识符。

公共函数

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

使用指明 operation_id 的消息构造该错误。

struct artifact_bundle

命名产物字节及其描述符的持有型集合。

公共函数

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

注册一个产物及其描述符。

包已关闭时抛出 fincore_error；产物名称为空或重复时抛出校验类 fincore_error。

inline void close() noexcept

封闭包，禁止后续注册；重复调用是安全的。

inline bool closed() const noexcept

返回包是否已被封闭。

公共成员

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

以确切的产物路径为键的产物字节。

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

保留在清单中的包级元数据。

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

以确切的产物路径为键的可选逐产物元数据。

每个描述符键都必须指向 artifacts 中的一个条目。清单记录每个产物的媒体类型、字节长度、实际产物字节的 SHA-256 和来源；省略的描述符使用旧版 octet-stream/空来源默认值。

bool is_closed = false

由 close() 设置的原生生命周期封闭标记。

产物是持有型字节串，因此关闭时没有需要释放的外部资源；关闭会阻止后续注册。

struct artifact_descriptor

描述一个产物的媒体类型和来源。

公共成员

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

此产物的使用方所使用的 MIME 类型。

没有显式描述符的旧版产物记为 application/octet-stream。

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

产物特定的来源元数据。

struct dense_array

具有显式维度的稠密行主序数值存储。

公共成员

std::vector<double> values

扁平的行主序值。

std::vector<std::size_t> shape

各维度大小。

struct execution_plan

与某个目录快照摘要绑定的已解析请求批次。

公共成员

std::string catalog_digest

计划解析所依据目录的摘要。

std::vector<operation_request> requests

按调用方提供顺序排列的请求。

struct operation_request

单个操作请求的快照，包含其输入和配置的摘要。

公共函数

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

创建请求并计算两个请求摘要。

operation_id 为空，或输入或配置键为空时，抛出 input_error。

公共成员

std::string operation_id

请求的操作标识符。

runtime_inputs inputs

转发给操作可调用对象的输入。

runtime_config config

记录的配置；绝不转发给可调用对象。

std::string input_digest

对输入的摘要，由构造函数计算。

std::string config_digest

对配置的摘要，由构造函数计算。

struct operation_spec

一个目录操作及其原生可调用对象的声明。

公共函数

std::string implementation_fingerprint() const

返回稳定的原生实现标识。

存在声明的 kernel_symbol 来源值时优先使用（相当于 Python 的 module:qualname）；否则标识为 domain:capability_id。

公共成员

std::string operation_id

唯一的目录标识符。

std::string capability_id

由各模式变体共享的叶能力标识符。

std::string domain

源领域，例如 metrics 或 report。

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

使用经校验的运行时输入调用的原生函数。

bool deterministic = true

操作结果是否可由分析会话缓存。

std::string rng_policy = "none"

随机状态策略；确定性内核为 none。

std::optional<std::string> semantic_mode

用于区分同一能力各变体的可选语义模式。

std::optional<std::string> mode_approval

必须与 semantic_mode 一同提供的可选批准令牌。

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

自由形式的来源元数据，例如所有者和内核符号。

struct runtime_result

操作值加上描述本次运行的字符串元数据。

公共成员

runtime_value value

操作可调用对象返回的值。

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

运行元数据，例如操作、输入和目录摘要。

struct runtime_result_payload

运行时结果的持有型、带版本表示。

副本持有各自的 DataFrame 缓冲区以及所有嵌套的报告/风险值。

公共成员

int schema_version = runtime_result_schema_version

负载 schema 版本。

runtime_value value

结果值。

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

结果元数据。

struct runtime_value

流经运行时层的持有型动态类型值。

公共类型

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>>

支持的备选类型；std::monostate 表示空值。

公共函数

runtime_value() = default

构造空值。

inline runtime_value(bool value)

构造布尔值。

inline runtime_value(int value)

从 value 构造 64 位整数值。

inline runtime_value(std::int64_t value)

构造 64 位整数值。

inline runtime_value(double value)

构造 double 值。

inline runtime_value(std::string value)

构造字符串值。

inline runtime_value(dataframe value)

构造 dataframe 值。

inline runtime_value(report_document value)

构造报告文档值。

inline runtime_value(risk_model_spec value)

构造风险模型规格值。

inline runtime_value(walk_forward_var_result value)

构造 walk-forward VaR 结果值。

inline runtime_value(risk_validation_report value)

构造风险校验报告值。

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

构造投资组合交易列表值。

公共成员

storage data

当前激活的已存备选类型。

enum class fincore::alignment_policy

时间序列索引对齐策略。

取值：

enumerator strict

要求每个帧的索引完全相同。

enumerator inner

保留每个帧中都存在的标签。

enumerator outer_dropna

保留在所有帧中都完整的标签，丢弃缺口。

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

按与 align_time_series 相同的策略对齐两个带标签的帧。

对与 align_time_series 相同的无效输入抛出 input_error。

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)

按第一轴长度对齐位置数组。

此重载有意不接受任一侧的带标签帧。数组经校验后原样返回；策略未知、形状不一致或第一轴长度不相等时抛出 input_error。

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

按 UTC 纳秒索引对齐 double 列帧。

保留所有列名和列顺序。不支持的列类型和重复索引会被拒绝。非 double 列不会被强制转换。策略未知或严格对齐发现索引不同时抛出 input_error。

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

面向 Iteration 8 P105 各领域的原生兼容运行时操作：attribution、factor_analysis、optimization、report.factor 以及原生数据快照模型。

每个声明都将确切的源操作 id 映射到现有原生内核。复合原生结果投影为持有型 report_document；表格型内核返回持有型 dataframe。rng_policy 为 none，每个操作都是确定性的。

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

针对生成该计划的目录运行 plan 中的每个请求。

结果按请求顺序返回。计划摘要与 catalog 不匹配时抛出 input_error，并传播各请求的校验错误。

operation_catalog fincore::builtin_catalog()

返回原生指标、风险和报告操作的内置目录。

内置报告操作的输入遵循锁定的源 ID。walk-forward 操作要求 returns (dataframe) 和 spec (risk_model_spec)。风险校验要求 result (walk_forward_var_result)，并接受可选的 index_name (string)。风险文档构建要求 report (risk_validation_report)，并接受可选的 title (string)。投资组合报告构建要求 returns (dataframe)，并接受可选的 benchmark、positions (dataframe)、transactions (vector<portfolio_transaction>)、rolling_window (integer) 和 title (string)。这些操作忽略 config 值，不会将其转发给领域函数。

runtime_result fincore::copy_for_consumer(const runtime_result &result)

返回运行时结果的持有型、值语义副本。

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

将 JSON 信封解析为运行时结果。

JSON 格式错误、对象键重复、UTF-8 无效、schema 版本不受支持或数字超出范围时，抛出 input_error。

runtime_result fincore::from_payload(const runtime_result_payload &payload)

校验负载并返回持有型运行时结果。

会检查支持的取值和嵌套形状。schema 版本不受支持或值表示无效时抛出 input_error。

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

检查原生能力依赖项，不可用时抛出。

原生调用方显式声明可用性，而无需导入可选的 Python 模块；不可用的能力会引发结构化 DependencyError。dependency 为空时默认为 module_name，message 为空时替换为 optional_dependency_missing 消息。

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

创建捕获并返回所提供声明的提供方。

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

metrics 的原生运行时声明。

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

每个声明都映射到现有原生内核。这些声明具有确定性，不消耗随机状态（rng_policy == "none"）。

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

返回时间序列帧的 UTC 归一化副本。

原生时间戳为 UTC 纳秒。因此 "UTC" 归一化返回持有型副本；命名时区转换不在此 API 范围内。normalize_tz 不是 UTC（按大小写不敏感方式比较）时抛出 input_error。

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

针对 catalog 校验每个请求并记录其摘要。

操作标识符未知时抛出 operation_resolution_error。

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

面向 portfolio、risk 和 simulation 源领域的原生兼容运行时操作（Iteration 8 / P105）。

返回的声明保留对账目录中的权威操作 ID。每个可调用对象都调用现有原生内核；没有专用 runtime_value 备选类型的结构化结果会序列化为 dataframe，其 schema 在操作的 provenance["input_schema"] 条目中说明。

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

运行一个操作并返回其值及运行元数据。

config 仅记录在结果元数据中；操作可调用对象接收运行时输入，绝不接收 config。

操作未知时抛出 operation_resolution_error，并传播可调用对象引发的校验错误。

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

返回 value 的确定性 SHA-256 摘要。

DataFrame 摘要包含索引值、列名、类型，以及 bool、character、integral、float、double 和 std::string 列的内容。其他列类型会被拒绝，以确保会话缓存键绝不遗漏输入数据。dataframe 列类型不受支持时抛出 input_error。

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

返回运行时结果的带版本语义摘要。

该摘要是对规范原生负载的 SHA-256，进行了域分隔和版本化。运行时长、运行标识符和路径值键等易变元数据被排除，以便等价结果比较相等。

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

将运行时结果序列化为确定性 JSON。

对于给定的原生 runtime_result，JSON 信封是确定性的。数值使用显式标签，以便非有限值和带符号零得以保留。无法表示的值会抛出 input_error。

runtime_result_payload fincore::to_payload(const runtime_result &result)

将运行时结果转换为持有型、带版本的负载。

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)

在检查形状、大小和有限值规则后返回持有型副本。

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)

在拒绝空键后返回类型化字符串键映射的副本。

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

返回覆盖了所提供元数据键的副本。

metadata 中存在的键替换现有值；result 中的其他元数据全部保留。

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

将包写入新的输出目录。

已存在的输出目录、不安全的产物路径和符号链接父级会被拒绝。包元数据和产物名保留在 .fincore-manifest.json 中；逐文件描述符在创建任何输出之前校验。包已关闭时抛出 fincore_error，路径或描述符被拒绝时抛出 input_error。

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

返回固定操作声明集合副本的工厂。

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

以非空配置名称为键的命名运行时配置。

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

以非空输入名称为键的命名运行时输入。

constexpr int fincore::runtime_result_schema_version = 1

当前运行时结果负载的 schema 版本。