registry

registry

Preflight registry: build, validate, register plugin checks.

Classes:

Name	Description
PreflightRegistry	Ordered, name-keyed view of the checks the orchestrator will run.

Functions:

Name	Description
register_preflight_check	Register a third-party PreflightCheck instance for inclusion in the registry.
reset_preflight_plugins	Clear all registered plugins and rebuild the registry from core checks.
build_registry	Merge one or more check sequences into a validated PreflightRegistry.
get_registry	Return the current preflight registry.

PreflightRegistry(checks) dataclass

Ordered, name-keyed view of the checks the orchestrator will run.

Constructed by :func:build_registry and treated as immutable. Iteration yields the PreflightCheck instances themselves (not their names), so for check in registry reads naturally; name-based access uses registry[name] / name in registry. Extend by calling register_preflight_check or rebuilding via build_registry; never mutate in place.

Attributes:

Name	Type	Description
checks	Mapping[str, PreflightCheck]	Insertion-ordered mapping from PreflightCheck.name to the check instance. Backed by types.MappingProxyType so the underlying dict is hidden from callers.

names property

The check names, in registry order.

register_preflight_check(check)

Register a third-party PreflightCheck instance for inclusion in the registry.

Plugin checks are included when the registry is (re)built by build_registry. The registry is sorted by stage, so each plugin lands in its stage block after core checks from the same stage rather than at the absolute end of the registry. The function takes an instance (not a class) and returns it unchanged, e.g.::

register_preflight_check(MyCheck())

The first dotted segment of name must not match a reserved core namespace; this is enforced here rather than at class-definition time so that core checks -- which are registered by direct inclusion in _CORE_CHECKS -- can legitimately use those prefixes.

Not thread-safe. Registration is expected at import / boot time -- serialize externally if you call this from multiple threads.

Source code in src/nemo_safe_synthesizer/preflight/registry.py

def register_preflight_check(check: PreflightCheck) -> PreflightCheck:
    """Register a third-party ``PreflightCheck`` instance for inclusion in the registry.

    Plugin checks are included when the registry is (re)built by
    ``build_registry``. The registry is sorted by stage, so each plugin
    lands in its stage block after core checks from the same stage rather
    than at the absolute end of the registry. The function takes an
    *instance* (not a class) and returns it unchanged, e.g.::

        register_preflight_check(MyCheck())

    The first dotted segment of ``name`` must not match a reserved core
    namespace; this is enforced here rather than at class-definition
    time so that core checks -- which are registered by direct
    inclusion in ``_CORE_CHECKS`` -- can legitimately use those
    prefixes.

    Not thread-safe. Registration is expected at import / boot time --
    serialize externally if you call this from multiple threads.
    """
    name = check.name
    prefix = name.split(".", 1)[0] if "." in name else name
    if prefix in _CORE_NAMESPACES:
        raise ValueError(
            f"Plugin {type(check).__qualname__} uses reserved core namespace {prefix!r}; "
            "prefix your check name with a unique namespace. "
            f"Reserved namespaces: {sorted(_CORE_NAMESPACES)}"
        )
    # Build the prospective registry *before* mutating module state so a
    # failed validation (duplicate name, bad ``requires``, stage order)
    # doesn't leave a poisoned entry in ``_PLUGIN_CHECKS`` that would
    # break every subsequent registration.
    candidate_plugins = tuple(_PLUGIN_CHECKS) + (check,)
    new_registry = build_registry(_CORE_CHECKS, candidate_plugins)
    _PLUGIN_CHECKS.append(check)
    global _REGISTRY
    _REGISTRY = new_registry
    return check

reset_preflight_plugins()

Clear all registered plugins and rebuild the registry from core checks.

Intended for use in tests and notebooks where a clean registry is required between runs. Not thread-safe; see register_preflight_check.

Source code in src/nemo_safe_synthesizer/preflight/registry.py

def reset_preflight_plugins() -> None:
    """Clear all registered plugins and rebuild the registry from core checks.

    Intended for use in tests and notebooks where a clean registry is
    required between runs. Not thread-safe; see ``register_preflight_check``.
    """
    global _REGISTRY
    _PLUGIN_CHECKS.clear()
    _REGISTRY = build_registry(_CORE_CHECKS)

build_registry(*sources)

Merge one or more check sequences into a validated PreflightRegistry.

Entries are stably sorted by stage so plugins registered from _PLUGIN_CHECKS (typically appended after core) slot into the appropriate stage block while preserving relative order within a stage.

Source code in src/nemo_safe_synthesizer/preflight/registry.py

def build_registry(*sources: Sequence[PreflightCheck]) -> PreflightRegistry:
    """Merge one or more check sequences into a validated ``PreflightRegistry``.

    Entries are stably sorted by ``stage`` so plugins registered from
    ``_PLUGIN_CHECKS`` (typically appended after core) slot into the
    appropriate stage block while preserving relative order within a
    stage.
    """
    merged = list(chain.from_iterable(sources))
    merged.sort(key=lambda c: _STAGE_ORDER[c.stage])
    _validate_registry(merged)
    return PreflightRegistry(checks=MappingProxyType({c.name: c for c in merged}))

get_registry()

Return the current preflight registry.

The registry is rebuilt each time a plugin is registered via register_preflight_check or cleared via reset_preflight_plugins. Always call this function rather than caching the result across registration boundaries.

Source code in src/nemo_safe_synthesizer/preflight/registry.py

def get_registry() -> PreflightRegistry:
    """Return the current preflight registry.

    The registry is rebuilt each time a plugin is registered via
    ``register_preflight_check`` or cleared via ``reset_preflight_plugins``.
    Always call this function rather than caching the result across
    registration boundaries.
    """
    return _REGISTRY