Register an engine in the msuiter engine registry — register_ms

`register_ms_engine()` is the extension entry point of the engine registry (ARCHITECTURE.md section 3.4). It stores a row keyed by `name` holding the S7 spec class (`engine_class`), the implementation function (`fit_fn`) and the governance fields `engine_version`, `contract_version` and `certified` (A17). Registry rows are data: the package itself ships an empty registry, and third-party packages register their engines from `.onLoad()`.

Usage

register_ms_engine(
  name,
  mode,
  engine_class,
  fit_fn,
  packages = character(0),
  tags = character(0),
  engine_version = NULL,
  contract_version = NULL,
  certified = NULL
)

Arguments

name: single lower-case snake_case engine name (the registry key; same grammar as the `MsEngine` `name` property).
mode: one of `"extract"` (signature discovery) or `"fit"` (reference-based fitting).
engine_class: an S7 class deriving from the abstract [MsEngine]. String sugar resolves through `engine_class()`, so its property defaults must form a valid spec (defaults for `name`, `mode`, `deterministic`).
fit_fn: the engine implementation. For `mode = "extract"` engines it is called as `fit_fn(engine, catalog = <MsCatalog>, k = <rank>)` and must return a list with `signatures` (channels x k, row-major) and `exposures` (k x samples); `ms_extract()` owns display normalization and the MsSignature assembly. For `mode = "fit"` engines the `ms_fit()` face contracts apply (see R/fit.R).
packages: character vector of required R packages reported by [required_pkgs()] (may be empty).
tags: character vector of free-form tags (may be empty), e.g. for benchmark filtering.
engine_version: required single string: version of the engine implementation.
contract_version: required single string: version of the msuiter registry/extension contract the engine was written against.
certified: required single string, one of `"certified"`, `"self-reported"`, `"unknown"`.

Value

`name`, invisibly.

Details

Trust boundary: registered engine code runs with your permissions. `certified` marks engines that passed the maintainer compatibility review; `"self-reported"` and `"unknown"` engines trigger a one-time warning per session when resolved by [match_ms_engine()].

Examples

if (FALSE) { # \dontrun{
# inside a third-party package's .onLoad():
msuiter::register_ms_engine(
  name = "othersig_kl", mode = "fit", engine_class = OthersigKlEngine,
  fit_fn = othersig_kl_fit, packages = "othersig",
  engine_version = "2.3.4", contract_version = "1",
  certified = "self-reported"
)
} # }