编码规范 · Vibe-Trading Wiki

所有对外暴露的数据结构使用 @dataclass(frozen=True) 并在 __post_init__ 中集中完成字段清洗与范围校验，构造即事实。
可选能力（FTS、语义链接、压缩、层级目录、质量衰减、GC）统一通过 src.config.accessor.get_env_config().memory.* 布尔开关惰性导入对应模块，避免启动期依赖。
所有写磁盘操作（添加/删除/更新 frontmatter/GC）均包裹在 memory_lock 上下文管理器中，采用临时文件 + os.replace 原子替换策略防止并发损坏。
治理账本每条记录固定保留 seq/prev_record_hash/record_hash 三个链字段，禁止调用方覆盖，并通过 compute_record_hash 统一生成哈希。
错误路径优先返回结构化结果（如 ChainVerificationResult、ChainBreak）而非抛异常，仅在不可恢复的链破坏时抛出 LedgerCorruptionError。
日志级别区分明确：可预期的失败（如 FTS 重建、语义链接发现）走 logger.debug，影响主流程的失败才走 logger.warning。