FastSim control-source conformance

This package gives control-source authors one small API for testing an installed FastSim plugin against the public Core lifecycle contract. It verifies the exact locked distribution and entry point, checks the factory descriptor, creates the plugin, exercises every asynchronous lifecycle hook, revokes services, and checks task cleanup. It is a test helper, not a runtime plugin.

Install

The release accepts the compatible FastSim >=0.1.0a15,<0.2 contract train. The conformance check still selects the plugin distribution and entry point exactly:

bash

python -m pip install fastsim-control-source-conformance==0.1.8

For local development in this repository:

bash

python -m pip install -e './packages/fastsim-control-source-conformance[dev]'

Test an installed control source

Use the exact values published by the plugin manifest and installed distribution. The manifest SHA-256 should come from the resolved FastSim lock or registry index.

python

from fastsim_control_source_conformance import (
    InstalledControlSourceSpec,
    make_control_source_binding,
    run_installed_control_source_conformance,
)

spec = InstalledControlSourceSpec(
    plugin_id="plugin://example/my-source",
    plugin_version="1.0.0",
    distribution="example-fastsim-source",
    distribution_version="1.0.0",
    entry_point="example.my-source",
    entry_point_value="example_fastsim_source:plugin_factory",
)

binding = make_control_source_binding(
    spec,
    manifest_sha256="0123456789abcdef" * 4,
    bindings={"actor": "robot"},
    config={"enabled": True},
)

report = run_installed_control_source_conformance(spec, binding=binding)
print(report.to_json())
report.raise_for_failure()

A passing report means the selected installed factory matches the locked identity and completed the public FastSim plugin lifecycle without leaking owned tasks. A failed report contains stable check codes in report.failures; calling raise_for_failure() turns it into one typed aggregate exception suitable for CI.

What this test does not prove

The runner executes trusted plugin code in-process. It is not an operating-system sandbox, physics test, task-success test, or performance benchmark. Test unknown or untrusted packages in an isolated process or container.

Package checks

bash

python -m pytest packages/fastsim-control-source-conformance
python -m ruff check packages/fastsim-control-source-conformance
python -m mypy packages/fastsim-control-source-conformance/src/fastsim_control_source_conformance