gen_platform/
lib.rs

1//! `gen-platform` — Rust-first canonical handle for the typed-
2//! dispatcher substrate primitive (typed-tagged-union catamorphism
3//! at a language boundary). Re-exports `TypedDispatcher` +
4//! `#[derive(TypedDispatcher)]`, ships a runtime `Dispatcher<T>`
5//! applicator for Rust consumers (controllers, daemons, reactive
6//! routers, migration runners, RBAC engines, render passes), and
7//! surfaces typed catalog primitives so any pleme-io crate can
8//! stand up a typed dispatch surface against any closed variant
9//! universe with one cargo add.
10//!
11//! ## Why a dedicated crate
12//!
13//! The `mk-typed-dispatcher.nix` primitive proves the value at the
14//! Nix dispatch layer. The same shape recurs across pleme-io
15//! wherever a closed variant set drives an action.
16//! `gen-platform` is the canonical
17//! Rust-side handle so consumers in pangea-operator, engenho
18//! controllers, magma plan walkers, anomalia remediations, shinka
19//! migrations etc. reach for the same primitive instead of hand-
20//! rolling another `match` ladder.
21//!
22//! ## Surface
23//!
24//! ```ignore
25//! use gen_platform::{Dispatcher, TypedDispatcher};
26//!
27//! #[derive(serde::Serialize, serde::Deserialize, gen_platform::TypedDispatcher)]
28//! #[serde(tag = "kind", rename_all = "kebab-case")]
29//! enum Migration {
30//!     AddColumn { table: String, column: String },
31//!     DropIndex { name: String },
32//! }
33//!
34//! let dispatcher = Dispatcher::<Migration, MyCtx, MyOverride>::new()
35//!     .helper("add-column", |variant, ctx| { /* ... */ Default::default() })
36//!     .helper("drop-index", |variant, ctx| { /* ... */ Default::default() })
37//!     .into_sealed()  // enforces variant coverage
38//!     .expect("every variant has a helper");
39//!
40//! let result = dispatcher.apply(&[migration_a, migration_b], &mut ctx);
41//! ```
42//!
43//! ## Re-exports
44//!
45//! - `gen_types::TypedDispatcher` — the reflection trait.
46//! - `gen_types::DispatcherVariant` — variant envelope shape.
47//! - `gen_macros::TypedDispatcher` — `#[derive]` macro.
48//!
49//! ## New primitives (this crate)
50//!
51//! - `Dispatcher<V, C, O>` — runtime applicator. Holds typed
52//!   helpers per variant kind. `into_sealed()` proves coverage at
53//!   construction time (every reflected kind has a registered
54//!   helper) — silent unknown variants become impossible.
55//! - `SealedDispatcher<V, C, O>` — the post-seal handle; `apply`
56//!   cannot fail on coverage anymore (proven at seal time).
57//! - `DispatcherError` — typed error for build-time issues
58//!   (missing coverage, duplicate helpers).
59//! - `MergeStrategy` — how to fold per-variant overrides.
60
61#![allow(clippy::module_name_repetitions)]
62
63pub mod catalog;
64pub mod composed;
65pub mod dispatcher;
66pub mod emit;
67pub mod merge;
68
69pub use catalog::{
70    DispatcherEntry, by_label as catalog_by_label, registered as catalog_registered,
71};
72pub use composed::{ComposedDispatcher, ComposedSource};
73pub use dispatcher::{Dispatcher, DispatcherError, SealedDispatcher};
74pub use emit::to_helpers_skeleton;
75pub use merge::MergeStrategy;
76
77// Re-exports — single canonical Rust handle.
78pub use gen_macros::{
79    BackendError, Discriminant, FromStrKind, IsVariant, OutcomeLattice, TypedDispatcher,
80};
81pub use gen_types::{DispatcherVariant, TypedDispatcher as TypedDispatcherTrait};
gen_platform/lib.rs

gen_platform/
lib.rs
