Experimental, WIP toolkit for on-chain operations built around an event-sourced state machine runtime.

WARNING: Not production-ready. Do not use on mainnet.

Start here:

• Design contract (source of truth): docs/redesign.md
• One-page overview + invariants: docs/architecture.md
• Contribution rules / CI parity: AGENTS.md

User-facing docs:

• CLI docs + output contract: bin/cli/README.md
• REST API docs: bin/rest-api/README.md

Crate docs:

• Core primitives (keystore + config models): crates/core/README.md
• Runtime: crates/machine/README.md
• Proc macros: crates/machine-derive/README.md
• SDK (orchestration helpers): crates/sdk/README.md
• Ops (proof op): crates/ops/proof-op/README.md
• Ops (keystore op): crates/ops/keystore-op/README.md
• Storage (EventStore, mem): crates/storages/event-store-mem/README.md
• Storage (EventStore, Postgres): crates/storages/event-store-postgres/README.md
• Storage (ArtifactStore, fs): crates/storages/artifact-store-fs/README.md
• Storage (ArtifactStore, S3/MinIO): crates/storages/artifact-store-s3/README.md

Design notes / planning:

• Nixfied vendoring boundaries: nixfied/VENDORED.txt

Canonical entrypoints:

nix run .#help
nix run .#dev
nix run .#check
nix run .#test
nix run .#ci -- --basic --summary
nix run .#ci -- --audit --summary
nix run .#ci -- --parity --summary
nix run .#ci -- --mode basic --summary

• Service hooks (for example run_hook MINIO_START) and service apps (for example nix run .#service::minio::start) share the same launcher path and argument/slot-env enforcement.
• Local supervisor wrappers in nixfied/local/default.nix (up, down, svc-*) are intentional prod-only overrides.
• mfm_cli is the compatibility passthrough wrapper; mfm_rest_api/svc-* now use strict typed contracts.
• Workflow-oriented strict json apps are available under mfm::keystore::* and mfm::run::*.
• nix run .#help currently lists project commands + module apps; invoke mfm::keystore::* and mfm::run::* apps directly by name.
• CI help/docs metadata comes from nixfied/project/ci.nix at commands.ci.api, and is mirrored into apps.<system>.ci.meta.nixfied.api.
• Project scripts should prefer framework policy helpers (for example start_service_should_register_cleanup) over duplicating SERVICE_* policy matrix logic.
• nix run .#dev intentionally uses start_service ... --cleanup for deterministic teardown.

• Explicit shell app classes are now enforced:
  • typed for strict text commands (check, test, build, mfm_rest_api, svc-*)
  • json for machine-output workflows (mfm::portfolio::snapshot, mfm::keystore::*, mfm::run::*, EVM artifact apps)
  • batch-runner for ci
  • passthrough retained for compatibility on mfm_cli
• Unknown args are rejected at the shell-contract boundary for typed/json commands before domain execution.
• New workflow-first wrappers (mfm::keystore::*, mfm::run::*) provide stable JSON automation surfaces while preserving mfm_cli.
• CI now validates command class policies and runtime behavior (including unknown-arg probes and JSON-shape checks) in shell-app-contracts.

• Runtime visibility:
  • nix run .#process::status
  • nix run .#process::status -- --all
  • nix run .#process::runs -- --all
  • nix run .#process::inspect -- <id>
  • nix run .#process::stop -- --run-id <id>
  • nix run .#process::stop -- --run-id <id> --scope slot-env
  • nix run .#process::stop -- --run-id <id> --dry-run
• Service diagnostics:
  • nix run .#service::postgres::events -- --limit 100
  • nix run .#service::postgres::log -- --lines 200
  • nix run .#service::helios::events -- --limit 100
• Policy controls (optional overrides):
  • SERVICE_REUSE_POLICY=never|same-root|same-slot|cross-run
  • SERVICE_OWNER_SCOPE=ephemeral|persistent
  • SERVICE_DISCOVERY_SCOPE=local|global
• Migration note:
  • MFM_KEEP_SERVICES has been removed from mfm::portfolio::snapshot.
  • Start reusable services explicitly via service::*::start, then inspect ownership with process::status.

nix run .#mfm_cli -- --help
nix run .#mfm_rest_api
nix run .#mfm::keystore::list
nix run .#mfm::run::status -- <RUN_ID>

MIT (see LICENSE).