#[non_exhaustive]pub struct ModuleManifest {Show 18 fields
pub module_id: String,
pub module_version: String,
pub protocol_ver: u8,
pub trust_tier: Option<TrustTier>,
pub ready: Option<bool>,
pub provides: Vec<ProviderRole>,
pub consumes: Vec<ConsumerRole>,
pub bindings: Option<Bindings>,
pub capabilities: Option<CapabilityDeclarations>,
pub events: Option<Vec<EventDeclaration>>,
pub self_signals: Option<Vec<SelfSignalDeclaration>>,
pub provenance: Option<ManifestProvenance>,
pub operation_delivery: BTreeMap<String, OperationDelivery>,
pub operation_payload: BTreeMap<String, OperationPayload>,
pub flow_operations: Option<Vec<String>>,
pub confirm_operations: Option<Vec<String>>,
pub rich_ui: Option<RichUiDescriptor>,
pub role_declarations: BTreeMap<String, Map<String, Value>>,
}Expand description
A module’s full declared participation in the subc mesh.
Construct via ModuleManifest::builder(), never a struct literal. Adding a
field to this struct would break every direct construction site; builder methods
are additive, so constructors written against an older revision continue
compiling when later fields land.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.module_id: String§module_version: String§protocol_ver: u8§trust_tier: Option<TrustTier>§ready: Option<bool>Whether this registered module is ready to receive new route binds.
Absence means ready, preserving the behavior of manifests emitted before
this field existed. This is a best-effort admission hint, not an invariant:
the daemon reads readiness separately from reserving a relay, so modules
must still tolerate an on_bind while not ready.
provides: Vec<ProviderRole>Existing role declarations; capability grammar claims deliberately live in
the separate CapabilityDeclarations block below.
consumes: Vec<ConsumerRole>§bindings: Option<Bindings>§capabilities: Option<CapabilityDeclarations>Optional capability-grammar declarations.
Omitting this block preserves the manifest contract used before capability grammar was introduced. A present block is static discovery metadata that the daemon validates before accepting a HELLO.
events: Option<Vec<EventDeclaration>>Events published as notices on ck.{acct}.event.{module_id}.{event}.v{N}.
The publisher serves the body; declared headers are filter hints, never authority.
None means the module has not declared events. Some(vec![]) affirmatively
declares that it publishes none. Absence remains absent on the wire.
Declarations are validated at HELLO and retained in the daemon registry,
but no client can read them yet: catalog.list, server.describe and
ck catalog do not return them, because subc-control’s CatalogEntry
has no field for them and adding one is a breaking change. A daemon built
before this field existed drops it silently. So a flow engine cannot yet
discover a module’s events from the catalog, and a module must not depend
on that discovery until a daemon that serves declarations is running.
self_signals: Option<Vec<SelfSignalDeclaration>>Periodic or event-driven behavior this module performs against an external surface, so later analysts can account for the resulting self-shaped time series.
Declarations describe the EFFECTIVE values in force at HELLO time. In
particular, a compile-time cadence constant belongs in
SignalCadence::Literal, while a cadence resolved from configuration
belongs in SignalCadence::Derived with a pointer to that effective
source. Both provenance stories are honest; copying a stale configured
value into a literal is not.
Ephemeral signals are out of scope for v1 because they are not durably declarable, not because they are harmless. A v2 reader must not interpret this field’s absence in a v1 manifest as a judgement about ephemerals.
None and Some(vec![]) are deliberately distinct on the wire: an
absent block means the module has not adopted this vocabulary (readers
treat it as zero signals but must not treat it as a survey answer),
while an empty list is an affirmative declaration that the module
examined its effects and claims none are declarable. Modules that mean
“no signals” should declare the empty list; None is what an
un-adopted manifest looks like, not a statement.
Convention for mutate-effect entries: where the mutation leaves a
per-observation tell on the surface itself (insula publishes the
relaxed usedPercent beside the raw figure, so any single reading
self-reports whether it was touched), name that tell in the
declaration’s note. A standing registry row says the module sometimes
mutates; the tell says whether THIS observation was mutated — a
consumer holding one sample can act on the second, not the first.
A named tell must exist on the wire independently of this registry:
the declaration points at evidence, it is never the evidence. A tell
that exists only because the manifest describes it is a claim
vouching for itself.
provenance: Option<ManifestProvenance>§operation_delivery: BTreeMap<String, OperationDelivery>Delivery hints keyed by management operation name; absent entries are unary.
Only "watch" on a declared query is subscribable; see Self::is_watch_operation.
Unknown strings are retained. A malformed map is dropped as a whole rather
than refusing HELLO. Older daemons silently drop this field.
operation_payload: BTreeMap<String, OperationPayload>Raw request payload limits keyed by declared management operation name. Watch operations cannot accept payloads. Empty maps preserve legacy bytes.
flow_operations: Option<Vec<String>>Management operations this module serves to a flow-scoped call.
Some(list) says the module admits a call under a scope carrying
flow_id only for the named operations and refuses every other one;
Some(vec![]) admits none. None means the module has not said, so a
reader (such as an install check) treats the answer as unknown and keeps
the module-wide view given by flow-scopes/v1 or call-modes/v1; it never
means “none”.
Meaningful only beside one of those capabilities in
capabilities.provides. Decoding drops the whole list, without refusing
HELLO, when the manifest declares neither capability, when the list is not
an array of strings, holds more than MAX_FLOW_OPERATIONS names, repeats
a name, or names something that is not a management operation of this same
manifest; see ModuleManifest::validate_flow_operations. The daemon only
relays the list through catalog.list and never enforces it: each module
refuses the operations it does not admit. Absence preserves legacy bytes,
and older daemons silently drop the field.
confirm_operations: Option<Vec<String>>Management operations this module guards by asking the person through
operator.confirm before it acts.
Some(list) names them; Some(vec![]) names none. None means the
module has not said, which a reader treats as unknown. A module asking
operator.confirm with kind operation names one of these in the
request’s operation; the daemon may answer without a prompt only for an
operation listed here, and prompts for everything else.
Decoding drops the whole list, without refusing HELLO, when it is not an
array of strings, holds more than MAX_CONFIRM_OPERATIONS names,
repeats a name, or names something that is not a management operation of
this same manifest; see ModuleManifest::validate_confirm_operations.
The daemon relays a valid list through catalog.list and refuses nothing
on its basis. Absence preserves legacy bytes, and older daemons silently
drop the field.
rich_ui: Option<RichUiDescriptor>An opaque rich-UI manifest descriptor discoverable from catalog.list.
The daemon validates the descriptor’s shape at HELLO and relays it without interpreting its schema or content. Absence preserves existing manifest bytes.
role_declarations: BTreeMap<String, Map<String, Value>>Opaque declarations keyed by role name, using the capability-name grammar.
Each role’s contract owns its entry’s schema. The daemon never interprets
the content: it checks object shape, keys and the whole-map size limit,
then relays the map through catalog.list. Malformed or oversized maps
are dropped whole at HELLO with a warning, without refusing registration.
Older daemons silently drop unknown manifest fields, so modules may declare
entries before every daemon understands this slot.
Implementations§
Source§impl ModuleManifest
impl ModuleManifest
Sourcepub fn builder(
module_id: impl Into<String>,
module_version: impl Into<String>,
) -> ModuleManifestBuilder
pub fn builder( module_id: impl Into<String>, module_version: impl Into<String>, ) -> ModuleManifestBuilder
Starts a manifest builder with the minimal identification fields.
protocol_ver defaults to the protocol version linked into this crate;
provides and consumes default to empty declarations. trust_tier
and bindings default to None because the daemon reads neither on any
production path; a required unread field forces producers to invent
fabricated values.
Sourcepub fn is_watch_operation(&self, name: &str) -> bool
pub fn is_watch_operation(&self, name: &str) -> bool
Whether a management query explicitly declares watch delivery.
Missing operations, non-query operations and unknown delivery strings are not watches. Such declarations are discovery hints, not HELLO refusals.
Source§impl ModuleManifest
impl ModuleManifest
Sourcepub fn validate_capability_grammar(&self) -> Result<(), CapabilityGrammarError>
pub fn validate_capability_grammar(&self) -> Result<(), CapabilityGrammarError>
Validate the typed capability block after serde has decoded it.
Source§impl ModuleManifest
impl ModuleManifest
Sourcepub fn validate_operation_payload(&self) -> Result<(), OperationPayloadError>
pub fn validate_operation_payload(&self) -> Result<(), OperationPayloadError>
Checks that payload declarations name unary management operations and
have limits in 1..=MAX_DECLARED_PAYLOAD_BYTES.
Source§impl ModuleManifest
impl ModuleManifest
Sourcepub fn validate_flow_operations(&self) -> Result<(), FlowOperationsError>
pub fn validate_flow_operations(&self) -> Result<(), FlowOperationsError>
Checks a present Self::flow_operations list: the manifest provides
flow-scopes/v1 or call-modes/v1, the list holds at most
MAX_FLOW_OPERATIONS distinct names, and each name is a management
operation of this manifest. An absent list is always valid.
Source§impl ModuleManifest
impl ModuleManifest
Sourcepub fn validate_confirm_operations(&self) -> Result<(), ConfirmOperationsError>
pub fn validate_confirm_operations(&self) -> Result<(), ConfirmOperationsError>
Checks a present Self::confirm_operations list: it holds at most
MAX_CONFIRM_OPERATIONS distinct names, and each name is a management
operation of this manifest. An absent list is always valid.