statechronicle 0.3.0

StateChronicle protocol engine: domain-extensible verifiable state and transitions (umbrella crate).
Documentation

statechronicle

What it is

The umbrella crate: the single dependency consumers add to use the whole protocol surface. It re-exports the twelve underlying library crates under collision-safe namespaces and surfaces the most-used types directly at the top level. It ships no storage, HTTP, or authority implementation.

Recommended consumer path in 0.3

Define native rules with StateProfile / TypedProfile, prepare through mutation::Preparer, then sign and commit a protected SignedMutation against one qualified ledger authority. Resolve unknown writes by original-identity recovery. For supplied proofs, use proof::claim::ClaimVerifier with an independent expectation and trusted key, explicitly choosing current or historical mode. Planning, signing and cryptographic proof validity alone are not durable success.

The native tutorial and durable ledger tutorial are standalone applications with their own lockfiles. See the consumer map and migration guide. Package version 0.3.0 contains these APIs; the qualification summary records the tested scope and limitations.

Protocol sections owned

§ Title Normative summary
§1 Summary What StateChronicle is and is not
§28 API Surface The public surface this facade exposes
§33 Example Full Stack Flow The end-to-end pipeline this crate wires
§37 Glossary Terminology used across the protocol

Key types

This crate re-exports the underlying library crates plus a curated top-level facade: Amount, ContentDigest, Signature, Commit, CommitScope, Event, Intent, Operation, Signed, StateProjection, StateType, SubjectId, TenantId, ResourceId, Executor, Ports, ValidatedIntent, StateAccumulator, StateRoot, ProfileRegistry, ProfileRules, StateProfile, TypedProfile, CustomState, ProofService, ProofPorts, and the authority types. portable:: exposes the existing bounded transition, codec and integrity APIs; the complete standard engine requires std.

How it's used

Add statechronicle as a dependency and use either the flat top-level names or the namespaced core::, domain::, executor::, commit::, proof::, accumulator::, intent::, profiles::, portable::, and ports:: forms. See the root README.md for the recommended standalone tutorials and legacy example map.

use statechronicle::{Amount, TenantId, executor::pipeline::Executor};

See it run

Fifteen runnable examples live in examples/: twelve behavioral demonstrations and three performance probes. The shared in-memory harness lives in examples/common/harness.rs; custom native profiles live in examples/common/domains.rs. Run behavioral examples with cargo run -p statechronicle --example <name> and performance probes with --release. Symbolic transactions demonstrate planning, not durable storage.

Example Demonstrates
inventory Unique asset lifecycle (mint → transfer → lock → unlock → restrict → restore → burn) with fail-closed rejections
currency Fungible balance lifecycle with an atomic debit + credit transfer and amount math
stack Consumable stack lifecycle
access Entitlement and meter lifecycles
marketplace All-or-nothing purchase-settlement planning via execute_batch
cross_tenant Cross-tenant planning via execute_cross_tenant
proofs State, ownership, and non-membership proofs
paid_asset Paid unique asset overlay: owner consent and hard delete
trade_value Asset/payment settlement planning with declared value legs
trade_cross_tenant Cross-tenant trade planning linked by a manifest
trade_bundle Declared multi-asset bundle settlement planning
custom_domains Static native profile registration and direct configuration reduction/decoding
throughput Direct reduction and canonical hashing
e2e_throughput Signed execution/indexing with optional commits and batching
parallel_throughput Independent executor/adaptor scaling

See the domain extension guide for consumer-defined state, command binding, authority, replay/proof verification and schema migration. Custom-domain integration tests exercise both configuration and equipment through the signed and durable paths.

Dependencies

The twelve library crates: statechronicle-core, statechronicle-domain, statechronicle-intent, statechronicle-executor, statechronicle-commit, statechronicle-accumulator, statechronicle-proof, statechronicle-profiles, statechronicle-ports, statechronicle-index, statechronicle-profile, statechronicle-portable. Dev-only: tokio, serde_json, ed25519-dalek, chrono, async-trait.

Tests

tests/: e2e.rs (full cross-crate lifecycle through real crates with in-memory port fakes), smoke.rs (compile-only facade resolution), common/ (shared harness and fakes), and custom_domains.rs (native domains, portability, fault injection, cancellation, replay and reordered/concurrent recovery).

Where it fits

The top of the crate stack: the entry point for consumers. It is the single place the protocol surface is presented; the underlying crates remain usable individually for finer-grained consumption.