zetamesh-flags

zetamesh-flags is a minimal Rust library for rule-based validation of state combinations.

It provides a small, deterministic core for enforcing consistency rules between named states without introducing a full state machine or workflow engine.

This crate is designed to be embedded as a foundational component in larger systems.

Status

Early development. The API is not yet stable and may change before a 1.0 release.

What Problem Does This Solve?

Many systems maintain internal states such as:

• Initialized / Running / Stopped
• Connected / Authenticated / Authorized
• Ready / Busy / Error

Over time, it becomes easy to accidentally allow invalid combinations:

• Running without initialization
• Error and Running active at the same time
• Mutually exclusive states coexisting

zetamesh-flags prevents these situations by construction.

Core Concept

The library manages a set of named flags (states) and a set of validation rules.

Rules describe relationships between states, such as:

• One state requires another
• Two states cannot coexist

All rules are evaluated together, every time a state change is attempted.

Rule Evaluation Model

All rules in a FlagSet are enforced atomically.

If any rule is violated:

• The operation is rejected
• The FlagSet state is not modified
• The system remains valid and consistent

This behavior is intentional and guaranteed.

Supported Rule Types

The following rule types are currently supported:

• Dependency — one state requires another to be active
• Mutual exclusion — two states cannot be active at the same time

Additional rule types may be introduced in the future, but the library will remain focused on static consistency constraints, not dynamic behavior.

Error Handling Model (Result)

Operations that may violate rules return a Result:

• Ok(()) → the operation was valid and applied
• Err(reason) → the operation was rejected

Important guarantee:

If an operation returns Err, the internal state is unchanged.

Ignoring a returned Result does not corrupt state. Doing so is considered a caller-side logic error, not a library bug.

Design Goals

• Prevent invalid state combinations
• Guarantee internal consistency at all times
• Make invalid transitions observable but non-fatal
• Keep the API small and explicit
• Avoid exposing enums, bitmasks, or numeric IDs
• Be suitable as a core for C / C++ / C# / Python bindings

Non-Goals

This library is intentionally not:

• A finite state machine (FSM)
• A workflow or orchestration engine
• An event system
• A dynamic rule engine

It focuses strictly on state consistency, not control flow.

Example

use zetamesh_flags::{FlagSet, Rule};

let mut service = FlagSet::new();

service.add_flag("Initialized");
service.add_flag("Running");

service.add_rule(Rule::dependency("Running", "Initialized"));

// Rejected: Running requires Initialized
assert!(service.activate("Running").is_err());

// State is still valid and unchanged
assert!(service.is_valid());

service.activate("Initialized").unwrap();
service.activate("Running").unwrap();

Installation

Add the crate to your project using Cargo:

cargo add zetamesh-flags

Or by editing your Cargo.toml directly:

[dependencies]
zetamesh-flags = "0.1"

This crate has no external runtime dependencies and is suitable for embedding in low-level or performance-sensitive systems.

Versioning & Stability

zetamesh-flags follows Semantic Versioning (SemVer) with the following policy:

• v0.x.y: API is considered unstable and may change between minor versions.
• v1.0.0: API will be considered stable; breaking changes will require a major version bump.

During the 0.x phase:

• Breaking changes may occur as the core model is refined.
• Such changes will be documented clearly in the CHANGELOG.md.

Consumers are encouraged to:

• Pin the minor version (0.1.*) if stability is required.
• Review release notes before upgrading.

License

This project is licensed under the Apache License, Version 2.0.

• Commercial use is permitted.
• Modifications and redistribution are allowed.

See the LICENSE file for full details.