IndrasNet108/fsm-governance-engine-lib

# FSM 治理引擎 [](https://doi.org/10.5281/zenodo.18394740) DOI (engine v0.1.1): https://doi.org/10.5281/zenodo.18394741 DOI (DLX overview v1.0): https://doi.org/10.5281/zenodo.18862312 在进行任何更改之前，请阅读 `CODEX_INSTRUCTIONS.md` 并严格遵守。 用于确定性验证完整性关键型、人工驱动和系统驱动流程的独立 Rust 库。 本项目实现了一个仅用于验证的 FSM 核心。它不执行操作、自动化决策或强制执行结果。 ## 核心创新 声明式、仅用于验证的 FSM，适用于完整性关键型流程，具有形式化定义的 invariant 和确定性可审计性。 ## 亮点 - 声明式 FSM 定义（JSON），包含用于 state、transition 和 invariant 的 schema。 - 仅用于验证的 FSM 核心，用于确定性流程验证。 - Invariant 作为一等工件（终止规则、禁止循环、必需的 transition）。 - 审计跟踪（`AuditEntry`，`AuditTrail`），提供序列化/导出指南。 - 治理的参考实现（`Grant`，`IdeaStatus`），用于展示集成模式。 ## 快速开始 ``` cargo test cargo run --example fsm_definition_loader ``` ## 快速验证（冒烟测试） 运行完整的测试套件： ``` cargo test ``` 验证声明式 FSM 定义是否符合 schema（严格模式）： ``` cargo run --bin fsm_validate -- docs/example_fsm_definition.json --schema docs/FSM_schema.json --strict ``` 预期：OK（严格验证）。 加载并解析示例定义（definition loader 示例）： ``` cargo run --example fsm_definition_loader # 已加载 4 个状态和 4 个 transitions。 ``` ## 安全说明 - 仅用于验证：该库不执行操作或强制执行结果。 - 确定性 transition 和显式契约；无效的 transition 会被拒绝。 - 声明式定义在使用前会经过 schema 验证。 - 审计记录是只追加的，并在验证范围内（如适用）进行确定性排序。 ## 明确的非目标 - 不执行或编排工作流。 - 不自动化决策或治理结果。 - 不涉及授权、身份或密钥管理。 - 无存储、网络或外部副作用。 ## 声明层 - Schema: `docs/FSM_schema.json` - Schema 概述: `docs/FSM_schema.md` - 示例: `docs/example_fsm_definition.json` - Invariant 语义: `docs/Invariants.md` ## 文档 - API: `docs/API.md` - 审计跟踪: `docs/AuditTrail.md` - 审计模型: `docs/AuditModel.md` - 贡献: `CONTRIBUTING.md` - 治理: `GOVERNANCE.md` - 行为准则: `CODE_OF_CONDUCT.md` ## 示例集成 ### 治理相关的流程验证示例 1. 实例化 `Grant::new(...)`，并在每次调用 `approve`、`activate` 或 `disburse` 时记录 `AuditEntry::new(...)`。 2. 通过 `serde_json::to_string(&trail.entries())` 持久化跟踪记录，并将其附加到治理报告中。 ### 金融流程相关的验证示例 1. 将 `GrantStatus` 替换为特定领域的 enum，同时复用 `AuditTrail`。 2. 每个审计条目都作为带有结构化元数据的不可变验证记录。 ### 合规性验证 pipeline 1. 构建一个类似 `ComplianceReport` 的 struct，派生 Borsh/Serde。 2. 使用 `AuditTrail` 辅助函数在转换阶段之前验证流程状态。 ## 示例脚本 - `cargo run --example dao_grant_flow` — 演示：创建拨款、记录审计条目、模拟投票、拨付并验证审计跟踪。预期：`Audit JSONL` 和 `Audit trail entries: 2`。 - `cargo run --example fsm_definition_loader` — 加载并验证 `docs/example_fsm_definition.json`。预期：`Loaded 4 states and 4 transitions.`。 - `cargo run --example governance_lifecycle` — 提案生命周期（draft → executed）。预期：`Proposal lifecycle complete: Executed`。 - `cargo run --example voting` — 治理投票元数据初始化。预期：`Voting initialized for proposal 200`。 - `cargo run --example treasury_flow` — 国库操作验证。预期：`Treasury operation validated: Transfer`。 - `cargo run --example audit_only_validation` — 不执行操作的审计跟踪验证。预期：`Audit JSONL` 和 `Audit-only validation complete: 1 entries`。 ## CI GitHub Actions 在 stable 和 nightly 版本上运行 fmt、clippy 和测试。 有关 CI 验证步骤，请参见 `docs/CI_validation.md`。 ## CLI 验证器 使用内置的验证器检查 JSON 定义： ``` cargo run --bin fsm_validate -- docs/example_fsm_definition.json ``` ## 下一步 1. 参考 `docs/API.md` 了解用法。 2. 在集成合规性日志记录时使用 `docs/AuditTrail.md`。 3. 使用 `docs/FSM_schema.json` 验证自定义 FSM 定义。 4. 查看 `docs/Invariants.md` 中的 invariant 指南。 5. 按照 `docs/RELEASE.md`，在测试/测试覆盖率完成后发布 crate。 ## 哲学基础（可选背景） 以下文档提供了更广泛的概念背景，对于使用或理解 FSM 治理引擎不是必需的。 指导 IndrasNet 的文明模型——其 MVP → 审计 → 拨款后演进、已弃用的 PDA 记忆层以及加密宪法——在 `INDRASNET_CIVILIZATION_FOUNDATION.md` 中进行了阐述。该文档明确说明了本体驱动的宪法、AI 管辖权、PDA 现实以及基于 CI 的宪法控制如何构成一个单一的自我纠错文明。 安全提示：该库验证声明的流程约束和 transition 规则，而不主张流程正确性，并且不执行操作、管理资产或替代人类决策。 IndrasNet® 是 IndrasNet OÜ 的注册商标。 除非明确声明，否则本项目不隶属于 IndrasNet OÜ 或得到其认可。

标签：Rust, 业务流程管理, 去中心化治理, 可视化界面, 审计追踪, 数据验证, 状态机, 网络流量审计, 通知系统