扩展

可选插件的扩展发现与快照契约。

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

class extension_hook

针对某一事件注册的钩子。

事件名在存储时会被裁剪空白；指纹按原样存储且必须非空白。回调必须可调用。事件与优先级相同的钩子在 extension_snapshot 内按指纹排序。

公共函数

extension_hook(std::string event, std::string fingerprint, extension_hook_callback callback, int priority = default_hook_priority, std::map<std::string, std::string> provenance = {})

创建一个钩子。

参数:

event -- Event name; surrounding ASCII whitespace is trimmed.
fingerprint -- Stable hook fingerprint; must not be blank.
callback -- Callback invoked by execute_hooks(); must be callable.
priority -- Lower values run first; defaults to default_hook_priority.
provenance -- Free-form provenance metadata.

抛出:

fincore_error -- With category ValidationError when event or fingerprint is blank, or callback is empty.

inline const std::string &event() const noexcept: 返回规范化后的事件名。

inline const std::string &fingerprint() const noexcept: 按传入原样返回指纹。

inline int priority() const noexcept: 返回钩子优先级。

inline const std::map<std::string, std::string> &provenance() const noexcept: 返回来源元数据。

inline const extension_hook_callback &callback() const noexcept: 返回回调。

class extension_snapshot

扩展操作、钩子与渲染器的不可变原生快照。

排序规则与固定版本的 Python 快照一致：操作按 operation_id，钩子先按事件分组再按 (priority, fingerprint)，渲染器按名称。钩子有意不做重复拒绝（源实现允许重复注册）；操作和渲染器则会拒绝重复。

公共函数

explicit extension_snapshot(std::vector<extension_operation> operations = {}, std::vector<extension_hook> hooks = {}, std::vector<renderer_registration> renderers = {})

创建快照、校验条目、排序并计算摘要。

操作与能力 id 必须以 extension. 开头且至少包含两个点。操作的 domain 必须为 extensions，实现指纹与随机数策略必须非空白；操作 id 必须唯一，且 semantic_mode 与 mode_approval 必须同时提供。钩子可以重复。渲染器名称必须唯一。钩子按事件、优先级、指纹排序；操作按 operation_id 排序；渲染器按名称排序。摘要为 to_json() 的 SHA-256。

参数:

operations -- Operation descriptors.
hooks -- Registered hooks.
renderers -- Registered renderers.

抛出:

fincore_error -- With category ValidationError for an invalid operation, a duplicate operation id or a duplicate renderer name.

inline const std::vector<extension_operation> &operations() const noexcept: 返回按 operation_id 排序的操作。

inline const std::vector<extension_hook> &hooks() const noexcept: 返回按事件、优先级、指纹排序的钩子。

inline const std::vector<renderer_registration> &renderers() const noexcept: 返回按名称排序的渲染器。

inline const std::string &digest() const noexcept: 返回 to_json() 的小写十六进制 SHA-256 摘要。

std::string to_json() const

返回用于计算摘要的紧凑、按键排序、ASCII 转义 JSON。

返回:: Canonical snapshot JSON.

extension_snapshot with_operation(extension_operation operation) const

返回多加一个操作的新快照。

接收者保持不变。操作按构造函数相同的方式校验，因此重复的操作 id 会被拒绝。

参数:: operation -- Operation to add.
抛出:: fincore_error -- With category ValidationError when the operation is invalid or its id is already registered.
返回:: New snapshot containing all existing entries plus operation.

extension_snapshot with_hook(extension_hook hook) const

返回多加一个钩子的新快照。

接收者保持不变。允许重复注册钩子。

参数:: hook -- Hook to add.
返回:: New snapshot containing all existing entries plus hook.

extension_snapshot with_renderer(renderer_registration renderer) const

返回多加一个渲染器的新快照。

接收者保持不变。重复的渲染器名称会被拒绝。

参数:: renderer -- Renderer to add.
抛出:: fincore_error -- With category ValidationError when the name is already registered.
返回:: New snapshot containing all existing entries plus renderer.

std::span<const extension_hook> hooks_for(std::string_view event) const

返回为 event 注册的钩子。

查找前会先规范化 event。返回的钩子按执行顺序排列：优先级升序，其次指纹升序。

参数:: event -- Event name.
返回:: View of matching hooks; empty when none are registered.

extension_value execute_hooks(std::string_view event, std::optional<extension_value> first = std::nullopt, const extension_keywords &keywords = {}) const

按优先级顺序执行 event 的钩子。

当 first 存在时，钩子从左到右依次变换它并返回最终值；当它不存在时，钩子只是通知，返回 monostate 值。

回调抛出的异常会传播给调用方。

参数:

event -- Event name; normalized before lookup.
first -- Value transformed by the hooks, or nullopt for a notification.
keywords -- Named scalar arguments passed to every callback.

返回:

Final transformed value, or monostate for a notification.

std::optional<extension_renderer_callback> renderer(std::string_view name) const

按名称查找渲染器。

查找前会先规范化 name；空白或未知名称返回 nullopt。

参数:: name -- Renderer name.
返回:: Copy of the renderer callback, or nullopt when not registered.

class renderer_registration

已注册的渲染器回调。

名称在存储时会被裁剪空白；指纹按原样存储且必须非空白。同一快照内渲染器名称必须唯一。

公共函数

renderer_registration(std::string name, std::string fingerprint, extension_renderer_callback renderer, std::map<std::string, std::string> provenance = {})

创建一条渲染器注册。

参数:

name -- Renderer name; surrounding ASCII whitespace is trimmed.
fingerprint -- Stable renderer fingerprint; must not be blank.
renderer -- Callback invoked by the host; must be callable.
provenance -- Free-form provenance metadata.

抛出:

fincore_error -- With category ValidationError when name or fingerprint is blank, or renderer is empty.

inline const std::string &name() const noexcept: 返回规范化后的渲染器名称。

inline const std::string &fingerprint() const noexcept: 按传入原样返回指纹。

inline const extension_renderer_callback &renderer() const noexcept: 返回渲染器回调。

inline const std::map<std::string, std::string> &provenance() const noexcept: 返回来源元数据。

struct discovered_extension

一份尚未执行的原生扩展清单。

字段名与 DiscoveredExtension 对应；value 使用原生的 component:symbol 约定，而不是 Python 导入路径。

公共函数

std::string fingerprint() const: 返回 to_json() 的稳定 SHA-256。

std::string to_json() const: 返回清单字段的紧凑、按键排序、ASCII 转义 JSON。

公共成员

std::string name: 扩展名称。

std::string group = "fincore.extensions": 入口点分组标签。

std::string distribution: 提供该扩展的发行包。

std::string value: component:symbol 目标。

struct extension_hook_invocation

传给钩子回调的载荷。

公共成员

extension_value value: 当前值；通知场景为 monostate。

extension_keywords keywords: 命名的标量参数。

struct extension_operation

原生扩展操作描述符。

它对应 fincore.runtime.specs.OperationSpec 中参与 ExtensionSnapshot.digest 的元数据子集；可调用对象与模式仍留在运行时目录中，而不是这个覆盖描述符里。

公共函数

std::string to_json() const

返回参与快照摘要的字段的紧凑、按键排序、ASCII 转义 JSON。

跨进程与跨平台稳定。

公共成员

std::string operation_id

以 extension. 开头

、至少包含两个点的 id。

std::string capability_id: 同一命名空间下的能力 id。

std::string domain = "extensions": 领域；必须为 extensions。

std::string implementation_fingerprint: 非空白的实现指纹。

std::optional<std::string> optional_extra: 可选的非空白额外标签。

bool deterministic = true: 该操作是否为确定性操作。

std::string rng_policy = "none": 非空白的随机数策略标签。

std::optional<std::string> semantic_mode: 可选的语义模式。

std::optional<std::string> mode_approval: 可选的模式批准。

std::map<std::string, std::string> provenance: 元数据；不包含在摘要 JSON 中。

struct loaded_extension

校验一份已发现清单的结果。

原生 ABI 不会导入代码或调用 dlopen；该记录即为加载校验边界。

公共成员

discovered_extension manifest: 已规范化并校验的清单。

std::string fingerprint: 规范化清单的 SHA-256。

std::vector<discovered_extension> fincore::extensions::discover_extensions(std::span<const discovered_extension> manifests, std::span<const std::string_view> groups = entry_point_groups())

发现请求分组的清单并确定性地排序。

每份清单通过裁剪其四个文本字段来规范化。即使清单所属分组未被请求，空白的必填字段也会被拒绝。规范化后分组不在 groups 中的清单会被忽略。结果按 (group, name, distribution, value) 稳定排序，因此重复项保持输入顺序。

参数:

manifests -- Candidate manifests.
groups -- Requested entry-point groups; defaults to entry_point_groups().

抛出:

fincore_error -- With category ValidationError when any candidate has a blank name, group, distribution or value.

返回:

Normalized manifests in deterministic order.

std::vector<discovered_extension> fincore::extensions::discover_extensions(const std::vector<discovered_extension> &manifests, std::span<const std::string_view> groups = entry_point_groups())

从 vector 发现并排序清单。

参数:

manifests -- Candidate manifests.
groups -- Requested entry-point groups; defaults to entry_point_groups().

抛出:

fincore_error -- With category ValidationError when any candidate has a blank name, group, distribution or value.

返回:

Normalized manifests in deterministic order.

std::span<const std::string_view> fincore::extensions::entry_point_groups() noexcept

返回默认使用的源实现入口点分组名称。

返回:: View of ENTRY_POINT_GROUPS; valid for the process lifetime.

loaded_extension fincore::extensions::load_extension(const discovered_extension &extension)

校验并规范化一份清单以供显式加载。

value 必须采用 component:symbol 形式，恰好一个冒号、各部分非空且不含 ASCII 空白字符。返回的清单已裁剪空白并计算指纹。不会打开动态库，也不会加载任何代码。

参数:: extension -- Manifest to validate.
抛出:: fincore_error -- With category ValidationError when a text field is blank or the value has the wrong shape.
返回:: Normalized manifest and its SHA-256 fingerprint.

std::string fincore::extensions::normalize_extension_name(std::string_view value)

裁剪注册名称两侧的 ASCII 空白。

保留大小写，与固定版本源实现中名称区分大小写的行为一致。当输入仅包含空白时返回空字符串。

参数:: value -- Text to trim.
返回:: Trimmed text, or an empty string when only whitespace was supplied.

std::vector<extension_operation> fincore::extensions::operations()

返回内置的扩展领域操作。

固定版本的源实现返回空元组：第三方通过快照注册带命名空间的操作。

返回:: An empty vector.

using fincore::extensions::extension_hook_callback = std::function<std::optional<extension_value>(const extension_hook_invocation&)>

钩子要么返回用于替换第一个参数的值，要么返回 nullopt 以保持其不变。

在通知式调用中返回值会被忽略，与源实现的 execute_hooks 契约一致。

using fincore::extensions::extension_keywords = std::map<std::string, extension_value>: 传给每个钩子回调的命名标量参数。

using fincore::extensions::extension_manifest = discovered_extension : 宿主应用提供的输入清单的原生名称。

using fincore::extensions::extension_renderer_callback = std::function<std::string(std::string_view request)>

渲染器是将请求键映射为稳定载荷的原生回调。

载荷格式由插件自行决定；快照只负责注册、排序与指纹计算。

using fincore::extensions::extension_value = std::variant<std::monostate, bool, std::int64_t, double, std::string>

一个原生钩子参数。

Python 钩子接受任意位置参数与关键字参数；原生 ABI 将其收窄为一个被变换的值加上命名的标量关键字。

constexpr std::array<std::string_view, 1> fincore::extensions::ENTRY_POINT_GROUPS{"fincore.extensions"}

来自固定版本 fincore.extensions.discovery 模块的源分组名称。

原生 ABI 使用显式提供的清单取代 importlib.metadata 入口点，同时保持相同的分组标签。

constexpr int fincore::extensions::default_hook_priority = 100

固定版本 Python ExtensionHook 值的原生等价实现。

Python 对象从回调派生 module:qualname 指纹；由于 C++ 可调用对象没有可移植的限定名，原生 ABI 要求显式提供该指纹。

除非另行提供，钩子使用优先级 100；优先级数值越小越先执行。