Skip to content

Ecosystem compatibility

The dynamic compatibility report for MIF's cross-repository contracts. It inspects the sibling repositories MIF consumes (their installed version and the presence of the prescribed surfaces) and renders a live compatibility matrix, rather than hard-coding sibling versions into the docs. The scpn-mif ecosystem CLI subcommand is a thin wrapper over it.

Contract

  • generate_ecosystem_report(...) — inspect each sibling under the code root and return an EcosystemReport (per-sibling SiblingReports, each with the prescribed-surface SurfaceReports and the detected version).
  • render_compatibility_matrix(report) — a human-readable matrix.
  • compatibility_report_json(report) — the machine-readable form.

Every sibling row exposes three orthogonal compatibility fields:

  • symbols_present says whether every prescribed source surface exists.
  • integration_gated says whether MIF integration is deferred or blocked.
  • evidence_blocked says whether external-reference or hardware evidence is still outstanding.

The legacy aggregate status remains available for consumers, but renderers use the three fields. For example, the delivered QUANTUM surfaces can report symbols_present=true, integration_gated=true, and evidence_blocked=false without being collapsed into one ambiguous deferred label.

Sibling inspection is read-only and import-isolated: a missing or unimportable sibling is reported as such, never fabricated. The report reflects whatever is actually present on the checkout, so it stays honest across environments.

Python API

ecosystem

Dynamic compatibility report for MIF-owned cross-repository contracts.

SurfaceSpec(name, detail, module=None, symbols=(), file_path=None, tokens=()) dataclass

One source or import surface MIF expects from a sibling repository.

SiblingSpec(key, package, module, repo_dir, role, lane, current_gate, surfaces, notes=()) dataclass

A sibling repository contract consumed by MIF.

SurfaceReport(name, status, detail) dataclass

Availability report for one sibling surface.

to_dict()

Return a JSON-serialisable representation.

SiblingReport(key, package, module, repo_path, role, lane, current_gate, source_version, import_version, import_status, import_detail, status, surfaces, notes) dataclass

Dynamic compatibility row for one sibling repository.

failed_surfaces property

Return required surfaces that were not found.

symbols_present property

Whether every prescribed source surface is present.

This is deliberately independent of integration scheduling and evidence gates: a deferred sibling can have every symbol MIF expects.

integration_gated property

Whether MIF integration is deferred or blocked despite source state.

evidence_blocked property

Whether external or hardware evidence remains outstanding.

to_dict()

Return a JSON-serialisable representation.

EcosystemReport(generated_at_utc, code_root, siblings) dataclass

Aggregate dynamic compatibility report for MIF ecosystem consumers.

by_key()

Return sibling rows keyed by repository identifier.

require(key)

Return a sibling row and raise when the report does not contain it.

to_dict()

Return a JSON-serialisable representation.

default_code_root()

Return the sibling repository root used by the live compatibility scan.

generate_ecosystem_report(code_root=None, *, generated_at_utc=None)

Inspect sibling source trees and optional runtime imports.

render_compatibility_matrix(report)

Render the dynamic ecosystem report as Markdown.

compatibility_report_json(report)

Return deterministic JSON for generated compatibility artifacts.