feat(agent): implement agent accountability framework with full TDD coverage#2
Merged
paraphilic-ecchymosis merged 28 commits intomainfrom Feb 3, 2026
Merged
Conversation
- Move outdated ROADMAP.md and AGENT_QUICKSTART.md to docs/archive/ - Create docs/developer/ with human-readable documentation: - quickstart.md, architecture.md, api.md, security.md - Create docs/llm/ with agent-optimized Sigil format (1-to-1 parity): - quickstart.sigil, architecture.sigil, api.sigil, security.sigil - Update README.md with accurate ~35K LOC stats and docs section - Keep BENCHMARK_REPORT.md at root for easy access Sigil format uses evidentiality markers (!, ~, ?) for trust levels and embeds markdown content in a structured document format.
…verification Critical security fixes for OSS release: ## API Key Hashing (moloch-api) - Replace DefaultHasher (SipHash) with BLAKE3 for cryptographic security - Add `new_strict()` constructor that enforces JWT secret requirements - Add comprehensive TDD tests for hash consistency and length ## Light Client Signature Verification (moloch-light) - Implement actual Ed25519 signature verification in `verify_signature()` - Previously always returned `true` - now properly validates signatures - Add tests for valid/invalid signatures and finality threshold ## Build & Metadata - Add rust-toolchain.toml pinning Rust 1.75 for reproducibility - Fix repository URL: workspace → moloch - Add crates.io keywords and categories ## Examples - Add examples/ directory with working code samples: - basic_event.rs: Create and sign audit events - mmr_proofs.rs: MMR operations and inclusion proofs - holocrypt_privacy.rs: ZK proofs, threshold, and PQC encryption ## Documentation - Add OSS_RELEASE_ROADMAP.md with TDD checklist Closes security issues identified in OSS readiness review.
Replace local path references with published crates.io versions: - arcanum-hash = "0.1" - arcanum-signatures = "0.1" Arcanum v0.1.0 was released on 2025-01-22. This removes the requirement for a sibling arcanum/ directory.
## Dependency Updates
- Update all Arcanum path dependencies to crates.io v0.1
- moloch-holocrypt: arcanum-{holocrypt,core,hash,signatures,symmetric,threshold,pqc,zkp}
- moloch-bench: arcanum-{holocrypt,pqc}
- Update rust-toolchain.toml to 1.89 (required by Arcanum crates)
## Clippy Fixes
- moloch-core/error.rs: Use Range::contains() instead of manual comparison
- moloch-core/error.rs: Allow unused impl_from_string macro (transitional)
- moloch-core/merkle.rs: Use div_ceil() instead of manual implementation
- moloch-core/merkle.rs: Allow dead_code on MerkleTreeBuffer (pre-allocation struct)
- moloch-mmr/mmr.rs: Use += operator instead of x = x + 1
## Formatting
- Run cargo fmt --all to fix formatting across all crates
Note: arcanum-pqc has an upstream dependency conflict (ml-kem uses
incompatible crypto-common versions) that needs to be fixed in Arcanum.
- Update Cargo.lock to use Arcanum 0.1.2 crates (fixes ml-kem dependency conflict) - Fix moloch-light/src/header.rs to use BlockHash.as_hash().as_bytes()
- Fix BlockHash.as_bytes() -> BlockHash.as_hash().as_bytes() in tests - Fix create_test_header() to use correct BlockHeader fields - Add chrono dev-dependency to moloch-light for tests - Update examples to use field access instead of method calls: - AuditEvent fields (event_time, event_type, outcome, actor) - MmrProof.siblings field - EncryptedEvent.header fields - Fix Mmr.node_count() -> Mmr.size() - Fix Mmr.root()? -> Mmr.root() (returns Hash not Result) - Fix EventType::Access -> EventType::AccessGranted
- Add #[allow(dead_code)] to structs kept for future use: - QueuedRequest in scheduler.rs - MockTransaction in mock.rs - Utxo, AnchorTxBuilder in tx.rs - PendingRequest in bridge.rs - EventMeta in concurrent_mempool.rs - ProviderRegistry in registry.rs - PendingRequest, RequestKind in sync.rs - MmapStorage in mmap.rs - SnapshotBuilder in snapshot.rs - Fix conditional imports for test-only dependencies - Remove unused imports across multiple modules - Prefix unused variables with underscore - Fix doctest in aligned.rs with complete example code - Add missing documentation for InRange variant - Fix unused parameter warning in verify_proof_data Build now completes with zero warnings from `cargo build`.
- Fix unused variables (prefix with _) - Fix field assignment outside initializer (use struct init syntax) - Fix file opened with create but truncate not defined - Fix loop counter warning (use enumerate()) - Fix sort_by -> sort_by_key - Fix if let collapsing - Add #[allow] attributes for intentional patterns: - clippy::large_enum_variant for BatchOp and BridgeMessage - clippy::module_inception for specs module - clippy::should_implement_trait for not() method - dead_code for unused test helpers - Add missing documentation for test helper - Run cargo fmt --all 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
CI uses `cargo clippy --all-targets -- -D warnings` which treats all clippy warnings as errors. This commit fixes all issues: - Add #[allow(dead_code)] for test utility functions (proptest.rs) - Use !is_empty() instead of len() > 0 (rkyv_types.rs) - Use sort_by_key with Reverse instead of sort_by (runtime.rs) - Add #[allow(clippy::module_inception)] for specs module - Use #[derive(Default)] with #[default] attribute where possible - Use struct initialization syntax instead of field reassignment - Use strip_prefix() instead of manual string slicing (auth.rs) - Remove unnecessary type casts (mmr_benchmarks.rs) - Remove redundant closures (crypto_benchmarks.rs) - Fix unused imports and variables in tests - Add #[allow(clippy::large_enum_variant)] where appropriate - Use or_default() instead of or_insert_with(Default::default) - Use enumerate() instead of explicit counter loop (proof.rs) - Fix collapsible match patterns (provider.rs) - Remove needless borrows for generic args All tests pass with `cargo test --lib` and `cargo clippy --all-targets -- -D warnings` now succeeds.
Per SDD methodology, documents gaps discovered during dead_code audit: Spec Gaps (need specification before implementation): - Mempool TTL and eviction policy - Bitcoin SPV verification flow - Sync protocol state machine - Snapshot format and builder API Premature Abstractions (recommend removal): - MockTransaction unused fields - ProviderRegistry (multi-provider not specced) - MmapStorage (alternative backend not in architecture) - MerkleTreeBuffer (optimization without benchmark) - QueuedRequest.queued_at (deadline handling not specced) - PendingRequest in bridge (federation protocol not detailed) Awaiting review and decision on each item before proceeding.
Reverse-engineered complete system specification from codebase analysis. Covers all 14 crates with: - Architecture overview and dependency graph - Core primitives (Hash, Keys, Events, Blocks, Proofs) - MMR specification with position numbering and operations - Storage layer with ChainStore trait and backends - Chain state management and mempool - PoA consensus with validator sets and finality - P2P networking protocol with message types - Event indexing with query DSL - External blockchain anchoring (Bitcoin OP_RETURN) - Privacy layer (HoloCrypt) with encryption and ZK - Light client protocol with compact proofs - Cross-chain federation with trust levels - Verification framework with invariants - REST/WebSocket API specification This document codifies Moloch's specifications as requested for spec-driven development methodology.
New documentation files: Architecture Diagrams (docs/diagrams/): - data-flow.md: Event lifecycle, query flow, proof generation, light client verification, and network data flow diagrams - consensus-sequence.md: Block production, proposer rotation, missed slots, Byzantine detection, finality calculation, and validator set changes - sync-sequence.md: Handshake, fast sync, header-first sync, warp sync, parallel peers, gossip mode, fork resolution - anchoring-sequence.md: Bitcoin anchoring flow, OP_RETURN format, SPV proof verification, multi-provider anchoring, failure recovery Operational Documentation: - deployment.md: Hardware requirements, installation, configuration, deployment modes, systemd service, HA setup, Bitcoin anchoring, backup/recovery, security checklist - operations.md: Monitoring, alerting, maintenance tasks, common operations, incident response runbooks, upgrades, performance tuning - configuration.md: Complete reference for all TOML config options with types, defaults, and examples Documentation Index: - INDEX.md: Complete map of all documentation with quick links by role (developers, operators, contributors, auditors) These documents support the master specification with practical guidance for deployment, operation, and troubleshooting.
This specification addresses gaps identified for agent accountability: 1. Causality Chain (Section 3) - CausalContext linking events to predecessors and human principals - Session management with depth limits - Efficient ancestry and descendant queries 2. Agent Identity Attestation (Section 4) - AgentAttestation binding keys to code/config/tools - TEE support for hardware-backed attestation - Attestation authority and registry model 3. Capability Model (Section 5) - Fine-grained capabilities with resource scope - Constraints: rate limits, time windows, usage limits - Delegation with depth limits and subset enforcement 4. Human-in-the-Loop Protocol (Section 6) - ApprovalRequest/Response workflow - Escalation policies with timeouts - Modification support for conditional approvals 5. Reasoning Traces (Section 7) - Structured goal, steps, decision, alternatives - Confidence scoring with uncertainty tracking - Integrity via trace hashing 6. Outcome Verification (Section 8) - OutcomeAttestation with evidence requirements - Idempotency tracking for retries - Dispute resolution protocol 7. Emergency Controls (Section 9) - SuspendAgent, RevokeAgent, GlobalPause actions - Propagation and enforcement requirements - Resolution and post-mortem workflow 8. Multi-Agent Coordination (Section 10) - CoordinatedAction with participant roles - Responsibility assignment (individual, shared, supervised) - Pipeline, parallel, and supervised patterns Also includes: - 11 new event types for agent accountability - 20+ invariants ensuring system correctness - Security considerations and threat model - Migration path from legacy events Follows Daemoniorum SDD best practices with explicit rules, data models, sequence diagrams, and worked examples.
Comprehensive test-driven development plan covering all 8 spec sections: Phase 1: Core Types and Causality Chain (45 tests) - CausalContext construction and validation - Session lifecycle and duration - Causal chain queries (ancestors, descendants) - Property tests for INV-CAUSAL-1 through INV-CAUSAL-4 Phase 2: Agent Identity Attestation (40 tests) - AgentAttestation validity and expiry - AttestationRegistry operations - Revocation handling - Property tests for INV-ATTEST-1 through INV-ATTEST-3 Phase 3: Capability Model (55 tests) - ResourceScope matching (specific, pattern, kind, all) - Constraint enforcement (max_uses, rate_limit, time_windows) - CapabilitySet permit/deny logic - Delegation with depth limits and subset enforcement - Property tests for INV-CAP-1 through INV-CAP-4 Phase 4: Human-in-the-Loop Protocol (50 tests) - ApprovalRequest lifecycle and expiry - ApprovalResponse validation and modifications - Escalation policies and timeouts - Property tests for INV-HITL-1 through INV-HITL-3 Phase 5: Reasoning Traces (35 tests) - ReasoningTrace structure validation - Step sequencing and integrity - Confidence thresholds and escalation - Alternative and factor requirements Phase 6: Outcome Verification (40 tests) - OutcomeAttestation types (success, failure, partial) - Evidence requirements by severity - Idempotency key handling - Dispute resolution Phase 7: Emergency Controls (45 tests) - Suspension (full, partial, timed) - Revocation (permanent) - Global pause with exceptions - Propagation and enforcement across nodes - Property tests for INV-EMERG-1 through INV-EMERG-3 Phase 8: Multi-Agent Coordination (50 tests) - Participant roles and coordinator requirement - Responsibility assignment (individual, shared, supervised) - Task dependencies and circular detection - Pipeline, parallel, supervised patterns - Disagreement detection and resolution Phase 9: Integration and Scenario Tests (30 tests) - End-to-end workflows (simple action, multi-agent, HITL, emergency) - Adversarial tests (attestation bypass, capability escalation, replay) Total: ~390 tests with property-based testing using proptest Includes: - Test generators for complex types - Fixtures for common test data - CI integration configuration - Test naming conventions - Definition of done per phase
Implement core agent accountability types following the TDD roadmap: - PrincipalId: Human/organization principals with user/org/service types - Session: Bounded contexts with duration/depth limits - CausalContext: Links events to predecessors and root human request - CrossSessionReference: For linked operations across sessions Key invariants implemented: - INV-CAUSAL-1: Child sequence must exceed parent sequence - INV-CAUSAL-2: Root events always have depth 0 - INV-CAUSAL-3: Depth bounded by session max_depth - INV-CAUSAL-4: Exactly one root event per session Includes: - 44 unit tests for agent module - 17 property tests verifying invariants - Error type extension for invalid_input validation - Re-exports from moloch-core root Part of agent accountability implementation per AGENT_ACCOUNTABILITY.md spec.
Implement agent attestation types following the TDD roadmap: - AgentAttestation: Cryptographic binding of agent identity to verifiable config - code_hash, config_hash, prompt_hash for reproducibility - Validity period with expiration checking - Authority signature verification - ToolAttestation: Attestation of available tools with versions and hashes - RuntimeAttestation: Runtime environment attestation - Support for TEE quotes (SGX, TDX, SEV-SNP, CCA) - Platform hash for measurement - AttestationRegistry: Registry for managing attestations - Registration with signature and authority validation - Verification at action time - Permanent revocation with reason tracking - Trusted authority management Key invariants implemented: - INV-ATTEST-1: Every agent action has valid attestation - INV-ATTEST-2: Attestation valid at action time - INV-ATTEST-3: Authority must be trusted - INV-ATTEST-4: Revoked attestations fail verification Includes 28 unit tests covering: - Construction and validation - Validity period checking - Signature verification - Registry operations - Revocation handling Part of agent accountability implementation per AGENT_ACCOUNTABILITY.md spec.
Implement capability-based authorization following the TDD roadmap: - CapabilityId: Unique 16-byte identifier for capabilities - CapabilityKind: Authorization categories (Read, Write, Execute, etc.) - Data: Read, Write, Delete - Tool: InvokeTool with specific tool ID or wildcard - Agent: SpawnAgent, DelegateCapability - Communication: SendMessage, ReceiveMessage on channels - Financial: Spend with currency and max amount - Admin: ModifyPermissions, ViewAuditLog - ResourceScope: What resources the capability applies to - Specific: Exact resource match - Pattern: Glob matching (e.g., "repository:org/*") - Kind: All resources of a type - All: Universal scope (requires explicit grant) - CapabilityConstraints: Usage limitations - max_uses: Limit total invocations - rate_limit: Requests per time period - time_windows: Business hours enforcement - requires_approval: HITL integration point - CapabilitySet: Collection of capabilities per agent - permits(): Check if action is authorized - delegate(): Create subset for child agents - Delegation depth tracking and enforcement - CapabilityCheck: Result type with Permitted/Denied/RequiresApproval Key invariants implemented: - INV-CAP-1: No default capabilities (explicit grant required) - INV-CAP-2: Delegation is subset of delegator's capabilities - INV-CAP-3: Delegation depth enforced - INV-CAP-4: Constraints enforced at action time Includes 24 unit tests covering: - Scope matching (specific, pattern, kind, all) - Constraint enforcement - Kind matching with wildcards - Capability set operations - Delegation chain management Part of agent accountability implementation per AGENT_ACCOUNTABILITY.md spec.
- Implement proper timezone support in TimeWindow.is_within() - Uses chrono-tz for timezone parsing - Handles overnight windows (e.g., 22:00-06:00) - Fails secure (denies access) on invalid timezone - Added 7 comprehensive tests - Add RequiredCapability enum for type-safe tool requirements - Replaces Vec<String> with Vec<RequiredCapability> - Matches CapabilityKind variants for consistency - Includes Display impl and helper methods - Exported from both agent module and lib.rs Tests: 103 unit + 53 property tests passing
Add comprehensive HITL types for human oversight of agent actions: - ApprovalRequest/Response for approval workflow - ApprovalRequestId with hex encoding - ProposedAction with builder pattern - ImpactAssessment with severity levels (Low/Medium/High/Critical) - ApprovalPolicy with multi-approver support - EscalationPolicy for timeout handling - ApprovalStatus tracking (Pending/Approved/Rejected/Expired/Escalated/Cancelled) - ApprovalContext linking to causality chain and attestation - ActionModifications for conditional approvals - ApprovalDecision variants (Approve/ApproveWithMods/Reject/RequestInfo/Defer) - Cost type for financial impact tracking - CancellationActor for tracking who cancelled requests Rules implemented per spec: - Rule 6.3.1: Approval triggers on High/Critical severity - Rule 6.3.2: Expiry handling with optional escalation - Rule 6.3.3: Signature verification on responses - Rule 6.3.4: Modification binding in approved requests - Rule 6.3.5: Rejection handling Tests: 24 unit tests covering all major workflows Total agent tests: 127 passing
Add comprehensive reasoning trace types for agent decision transparency: - TraceId: Unique 16-byte identifier with hex encoding - Goal/GoalSource: Goal representation with source tracking (UserInstruction, Derived, System) - Priority: Goal priority levels (Low/Normal/High/Critical) - ReasoningStep: Individual reasoning steps with actions/observations - StepAction: Retrieve/Analyze/ToolCall/Delegate/Decide variants - Decision: Final decision with rationale and success criteria - Confidence: Score (0.0-1.0) with breakdown, uncertainties, thresholds - Alternative: Considered alternatives with rejection reasons - Factor: Influencing factors with evidence Key features: - Integrity verification via trace_hash - Completeness validation per spec rule 7.3.2 - Confidence thresholds per spec rule 7.3.5: - < 0.3: should_reject() - < 0.5: requires_approval() - < 0.7: should_warn() Also updated ApprovalContext to include optional reasoning_trace field. Tests: 26 unit tests for reasoning module Total tests: 272 passing
Implement outcome verification types per spec section 8: - OutcomeAttestation with builder for signed outcome records - ActionOutcome enum (Success, PartialSuccess, Failure, Pending, RolledBack) - Evidence types (DataHash, ExternalConfirmation, Receipt, Visual, LogEntries, ThirdPartyAttestation) - Attestor enum (SelfAttestation, ExecutionSystem, Monitor, HumanObserver, CryptographicProof) - IdempotencyKey and IdempotencyRecord for action idempotency - OutcomeDispute and DisputeStatus for dispute resolution Evidence sufficiency rules per spec rule 8.3.3: - Low severity: self-attestation sufficient - Medium severity: at least one external evidence - High severity: multiple independent sources - Critical severity: cryptographic proof or human verification Adds 29 new tests (301 total).
Implement emergency control types per spec section 9: - EmergencyAction enum (SuspendAgent, RevokeAgent, TerminateSession, RevokeCapability, BlockResource, GlobalPause, RollbackActions) - SuspensionScope enum (Full, Capabilities, Resources) - EmergencyEvent with builder for declaring emergencies - EmergencyPriority (Low, Medium, High, Critical) with response times - EmergencyResolution for closing emergencies - Resolution enum (FalseAlarm, Fixed, AgentRemoved, RestrictionsActive, Escalated) - PostMortem for incident analysis - EmergencyTrigger with recommended priority logic Implements spec rules: - Rule 9.3.1: Authorization checks - Rule 9.3.2: Propagation support - Rule 9.3.3: Enforcement helpers (affects_agent, is_permanent) - Rule 9.3.5: Resolution requirement tracking Adds 25 new tests (326 total).
Implement multi-agent coordination types per spec section 10: - CoordinatedAction with builder for coordinated agent actions - CoordinationId, TaskId - unique identifiers - CoordinationType (Parallel, Pipeline, Consensus, Supervised, Competitive) - Participant with ParticipantRole (Coordinator, Peer, Supervisor, etc.) - Responsibility (Individual, Shared, Delegated, Supervised) - Task, TaskDependency, CoordinatedActionSpec - FailureHandling (AbortAll, ContinuePartial, Retry, Escalate) - CoordinationProtocol (TwoPhaseCommit, Consensus, LeaderFollower, Async) - CoordinationStatus and CoordinationResult with metrics - CoordinationEvent for lifecycle tracking Implements spec rules: - Rule 10.3.1: Exactly one coordinator requirement (validated in build) - Rule 10.3.3: Shared responsibility must sum to 1.0 (validated in build) - Rule 10.3.4: Atomic recording support via CoordinationResult - Rule 10.3.5: Disagreement events for resolution tracking Adds 22 new tests (348 total).
Comprehensive integration tests verifying cross-module interactions for agent accountability features: - Complete agent action flow (session → attestation → capability → reasoning → outcome) - HITL approval workflow with proper context creation - Multi-agent coordination with responsibility tracking - Emergency response declaration and resolution - Capability constraints and delegation - Reasoning confidence triggering approval requirements - Evidence requirements by severity level - Attestation expiry detection - Session boundary enforcement Adversarial tests: - Forged attestation signature rejection - Forged outcome signature rejection - Coordination without coordinator validation - Shared responsibility sum validation Also fixes unused EventId import in coordination.rs by moving it to test module. Test count: 361 total (348 unit + 13 integration)
SDD+TDD roadmap addressing all findings from the full branch code
review of Phases 1-9. Organized into 9 remediation phases (~103 tests):
P0 - Signature verification hardening (outcome attestor binding,
coordination commitment verification)
P1 - Capability lifecycle completion (revocation, delegation chains),
type system hardening (encapsulation, timestamp newtype)
P2 - Evidence classification refinement, builder/error consistency,
audit event integration, test coverage hardening, idempotency store
P3 - HashMap key type safety
Each phase follows RED-GREEN-REFACTOR with concrete test code,
spec invariant references (INV-*), and implementation sketches.
Reflect the current state of the project including the new agent accountability framework (12 modules, 242 tests), updated line counts (~48,700 lines across 113 source files), and accurate documentation tree.
paraphilic-ecchymosis
changed the title
- Format: run cargo fmt across all crates - Clippy: remove unnecessary u32 casts in capability.rs time window - Docs: fix broken intra-doc link (`approval` -> `hitl`) in agent/mod.rs - Test: fix flaky concurrent_mempool multithread test by using unique keys per event to avoid timestamp-based deduplication, and separating producer/consumer phases for deterministic accounting
paraphilic-ecchymosis
deleted the
claude/review-crypto-audit-lib-52H9p
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Modules
Also included
Test plan