Module plugin_contract 

The versioned plugin API stability contract (issue #1601).

Autumn’s plugin system is a compile-time Rust surface: a plugin depends on autumn-web, implements Plugin, and is mounted with AppBuilder::plugin. That makes most breakage a compiler error rather than a production incident — but only if plugin authors know which APIs they may build on, and get told when the framework they are mounted into is not the one they were written for.

This module is the machine-readable half of that contract. It carries three things:

1. PLUGIN_SURFACES — every plugin-facing API, declared Stable or Experimental. docs/plugins.md renders the same list, and scripts/check-plugin-surface.sh fails when the two disagree.
2. PluginContract — what a plugin declares about itself: the autumn-web range it supports and any experimental surface it knowingly leans on. A plugin returns one from Plugin::contract.
3. evaluate — the compatibility verdict, and the diagnostic an incompatible pairing produces.

The SemVer policy, by tier

Tier	Promise	What a break costs
SurfaceTier::Stable	Covered by STABILITY.md. Below 1.0 a break needs a minor bump, a migration guide, and a filled Plugin authors section in that guide; from 1.0 on it needs a major.	A build failure with an upgrade path.
SurfaceTier::Experimental	May change in any release, including a patch. Declare it with PluginContract::uses_experimental so autumn plugin-check can report it.	A build failure you opted into.

Declaring a contract

use autumn_web::app::AppBuilder;
use autumn_web::plugin::Plugin;
use autumn_web::plugin_contract::PluginContract;

struct MyPlugin;

impl Plugin for MyPlugin {
    fn contract(&self) -> Option<PluginContract> {
        Some(
            PluginContract::new(env!("CARGO_PKG_NAME"))
                .plugin_version(env!("CARGO_PKG_VERSION"))
                .autumn_web("0.9"),
        )
    }

    fn build(self, app: AppBuilder) -> AppBuilder {
        app
    }
}

Structs

PluginCompatibilityError

An incompatible plugin/framework pairing, rendered as the diagnostic a user sees.

PluginContract

What a plugin declares about its own compatibility.

PluginSurface

One plugin-facing API, with the tier it is declared at.

Enums

ContractVerdict

The outcome of checking a PluginContract against a framework version.

SurfaceTier

Stability tier of a plugin-facing API.

Constants

AUTUMN_WEB_VERSION

The autumn-web version this build presents to plugins.

PLUGIN_CONTRACT_MARKER

Machine-readable stderr marker carrying the declared plugin contracts of a built application.

PLUGIN_SURFACES

Every plugin-facing API Autumn declares, sorted by name.

Functions

evaluate

Check a plugin’s declared autumn-web range against a framework version.

experimental_surface_names

The names of every SurfaceTier::Experimental surface, in registry order.

lockstep_contract

Builds the compatibility contract a first-party plugin declares from Plugin::contract (issue #1601).

lockstep_range

The autumn-web range a crate released in lockstep with the framework declares support for.

stable_surface_names

The names of every SurfaceTier::Stable surface, in registry order.

surface

Look a surface up by its canonical name.