Human-Touch Gateway — Async Tokio Review Gate
Version: 1.0.0
Status: Implementation Complete
Architecture: Async Tokio Runtime with WORM Audit Trail
Purpose: Enforce human review before ANY code changes land
Overview
The Human-Touch Gateway is a complementary component to the Sovereign Event Bus (SEB) that implements a human-centered review and approval workflow. It ensures that:
- Zero auto-commits — Every change requires explicit human approval
- Clear review workflow — Natural-language prompts, evidence-based decisions
- Cryptographic accountability — All approvals are sealed and auditable
- Async-first architecture — Tokio runtime with non-blocking I/O
- WORM audit trail — Immutable record of all decisions
Architecture
┌──────────────────────────────────────────────────────────────┐
│ Pending Changes Stream │
│ (from agents via MPSC channel) │
└────────────────────────┬─────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Review Queue (Tokio async) │
│ - Formats changes for human review │
│ - Manages in-flight approval state │
│ - Timeout on long-pending reviews │
└────────────────────────┬─────────────────────────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────────┐ ┌─────────────┐
│ Approve │ │ Reject with │ │ Inspect │
│ │ │ Reason │ │ Full Diff │
└────┬────┘ └──────┬───────┘ └─────────────┘
│ │
└────────────────┼──────────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────┐
│ Commit Gateway │ │ Reject & Log │
│ (Git + Ed25519) │ │ │
└────────┬─────────┘ └──────────────┘
│
▼
┌───────────────────────┐
│ WORM Audit Log JSON │
│ (immutable trail) │
└───────────────────────┘
Components
1. ReviewQueue (async/review_queue.rs)
Responsibility: Manage the queue of pending changes awaiting human approval.
Key Features:
- Async MPSC channel for incoming changes
- DashMap for O(1) status lookups
- Timeout detection for long-pending reviews
- Natural-language formatting for humans
Public API:
pub async fn process_queue(
self,
gateway: CommitGateway,
audit_log: AuditLog,
) -> Result<()>
pub async fn approve_change(
&self,
change_id: &str,
reviewer: &str,
audit_log: &AuditLog,
) -> Result<()>
pub async fn reject_change(
&self,
change_id: &str,
reviewer: &str,
reason: &str,
audit_log: &AuditLog,
) -> Result<()>
pub fn status(&self) -> QueueStatus
2. CommitGateway (commit_gateway.rs)
Responsibility: Enforce human approval requirements and manage git commits.
Key Features:
- Pre-commit verification hooks
- Approval certificates with Ed25519 signatures
- Blake3 hashing of evidence
- Reject all auto-commits (no
[auto]tags allowed) - Commit messages include:
Approved-By,Review-Date,Evidence,Change-ID
Public API:
pub async fn verify_approval_required(&self, change_id: &str) -> Result<()>
pub fn create_approval_certificate(
&self,
change_id: &str,
reviewer: &str,
evidence_url: &str,
) -> Result<ApprovalCertificate>
pub fn commit_with_approval(
&self,
change_id: &str,
reviewer: &str,
message: &str,
evidence_url: &str,
) -> Result<String>
pub fn check_no_auto_commit(&self, message: &str) -> Result<()>
3. AuditLog (audit_log.rs)
Responsibility: Maintain immutable WORM audit trail of all review decisions.
Key Features:
- Atomic WORM writes (append-only, no overwrites)
- JSON-line format for streaming/querying
- Supports: submitted, approved, rejected, committed events
- Generate audit summaries (changes by reviewer, decision stats)
Public API:
pub async fn log_submitted(&self, change: &PendingChange) -> Result<()>
pub async fn log_approval(
&self,
change_id: &str,
reviewer: &str,
description: &str,
) -> Result<()>
pub async fn log_rejection(
&self,
change_id: &str,
reason: &str,
reviewer: &str,
) -> Result<()>
pub async fn log_commit(
&self,
change_id: &str,
commit_hash: &str,
reviewer: &str,
) -> Result<()>
pub async fn generate_summary(&self) -> Result<AuditSummary>
Usage
Interactive Mode
cd seb/human_touch
cargo run -- --repo-path /path/to/repo --verbose
Output:
📝 Human-Touch Gateway Interactive Mode
Commands: 'submit', 'status', 'help', 'exit'
┌─────────────────────────────────────────────────────────────┐
│ HUMAN REVIEW REQUEST │
├─────────────────────────────────────────────────────────────┤
│ ID: change-abc123
│ Agent: kernel-builder
│ Time: 2026-07-25 14:23:45 UTC
│ Status: ⏳ AWAITING REVIEW
├─────────────────────────────────────────────────────────────┤
│ DESCRIPTION:
│ Add phase 4 loop invariant proof
├─────────────────────────────────────────────────────────────┤
│ EVIDENCE:
│ https://github.com/snapkittywest/proof-link/phase4-inv
├─────────────────────────────────────────────────────────────┤
│ FILES MODIFIED: 3
├─────────────────────────────────────────────────────────────┤
│ DECISION:
│ ✅ approve change-abc123 - Approve and commit
│ ❌ reject change-abc123 - Reject with reason
│ 📝 inspect - Show full diff
└─────────────────────────────────────────────────────────────┘
🤔 Awaiting human review. Enter 'approve <id>' or 'reject <id> <reason>'
Daemon Mode (with Webhook)
cargo run -- --daemon --webhook-port 8080 --repo-path /path/to/repo
Agents submit changes via HTTP POST:
curl -X POST http://localhost:8080/changes \
-H "Content-Type: application/json" \
-d '{
"id": "change-xyz",
"description": "Fix edge case in validation",
"evidence": "https://example.com/pr/123",
"agent_name": "verifier-agent",
"files": ["src/validator.rs"]
}'
Programmatic API
use seb_human_touch::{ReviewQueue, CommitGateway, AuditLog};
use tokio::sync::mpsc;
#[tokio::main]
async fn main() -> Result<()> {
let (tx, rx) = mpsc::channel(100);
let queue = ReviewQueue::new(
rx,
"/repo/path".into(),
"audit.json".into(),
100,
)?;
let gateway = CommitGateway::new("/repo/path".into(), 3600)?;
let audit = AuditLog::new("audit.json".into())?;
// Spawn processor
tokio::spawn(queue.process_queue(gateway.clone(), audit.clone()));
// Submit a change
let change = PendingChange {
id: "test-001".to_string(),
description: "My feature".to_string(),
evidence: "https://pr.example.com".to_string(),
agent_name: "builder-agent".to_string(),
created_at: Utc::now(),
files: vec!["src/main.rs".to_string()],
diff: "...".to_string(),
};
tx.send(change).await?;
// Later: approve via API
queue.approve_change("test-001", "human@example.com", &audit).await?;
Ok(())
}
Commit Message Format
Every commit created by the Human-Touch Gateway includes:
feat: Add phase 4 loop invariant proof
Approved-By: Jessica White <jessicalw34@gmail.com>
Review-Date: 2026-07-25T14:23:45Z
Evidence: https://github.com/snapkittywest/proof-link/phase4-inv
Change-ID: change-abc123
Co-Authored-By: Human-Touch Gateway <human-review@snapkitty.ai>
Validation Rules:
- ✅ Must have
Approved-Byfield (not auto-commits) - ✅ Must have
Review-Datein ISO8601 format - ✅ Must have
EvidenceURL - ✅ Must have
Change-IDfor audit trail - ❌ Rejects commits with
[auto]tags - ❌ Rejects empty messages
Audit Trail Format
WORM audit log in HUMAN_REVIEW_LOG.json:
{"version":"1.0.0","type":"WORM_AUDIT_LOG","created_at":"2026-07-25T14:00:00Z","entries":[]}
{"timestamp":"2026-07-25T14:23:45.123Z","event_type":"CHANGE_SUBMITTED","change_id":"change-abc123","agent_name":"kernel-builder","reviewer":null,"decision":"AWAITING_REVIEW","reason":null,"commit_hash":null,"evidence_url":"https://github.com/snapkittywest/proof-link"}
{"timestamp":"2026-07-25T14:24:12.456Z","event_type":"CHANGE_APPROVED","change_id":"change-abc123","agent_name":"human-touch","reviewer":"jessica","decision":"APPROVED","reason":"Proof verified, logic sound","commit_hash":null,"evidence_url":null}
{"timestamp":"2026-07-25T14:24:13.789Z","event_type":"CHANGE_COMMITTED","change_id":"change-abc123","agent_name":"human-touch","reviewer":"jessica","decision":"COMMITTED","reason":null,"commit_hash":"a1b2c3d4e5f6","evidence_url":null}
Integration with SEB
The Human-Touch Gateway integrates with the SEB stack:
┌─────────────────────┐
│ Agent (Kernel, │
│ Runtime, etc.) │
└──────────┬──────────┘
│ emit change
▼
┌──────────────────────────────────────┐
│ Human-Touch Gateway │
│ - Review Queue │
│ - Commit Gateway │
│ - Audit Log (WORM) │
└──────────────────────────────────────┘
│ approved
▼
┌──────────────────────────────────────┐
│ SEB L2 Runtime (Erlang/OTP) │
│ - Event Bus │
│ - Routing │
│ - Partition Management │
└──────────────────────────────────────┘
Flow:
- Agent completes work (e.g., KERNEL agent verifies proof)
- Agent emits
PendingChangeto human-touch MPSC channel - ReviewQueue formats and prompts human
- Human approves with
approve <id>command - CommitGateway creates git commit with approval metadata
- AuditLog records decision with timestamp + evidence
- SEB routes the committed change downstream
Key Properties
1. No Auto-Commits (Zero-Trust on Code)
// This will be rejected:
gateway.check_no_auto_commit("[auto] regenerate stubs")?;
// Error: Auto-commits rejected. All changes require human approval.
// This will be rejected:
gateway.check_no_auto_commit("")?;
// Error: Commit message cannot be empty
// This will be accepted:
gateway.check_no_auto_commit("feat: add feature\n\nApproved-By: Human")?;
// OK
2. Cryptographic Accountability
Each approval creates a certificate:
let cert = gateway.create_approval_certificate(
"change-abc123",
"jessica",
"https://evidence.link",
)?;
// Returns:
ApprovalCertificate {
change_id: "change-abc123",
reviewer: "jessica",
approval_time: "2026-07-25T14:23:45Z",
evidence_hash: "a1b2c3d4...", // Blake3 hash
signature: "sig_hex...", // Ed25519 signature
}
3. Immutable Audit Trail
All decisions are append-only:
audit_log.log_submitted(change).await?; // Write 1
audit_log.log_approval(id, reviewer, desc).await?; // Write 2
audit_log.log_commit(id, hash, reviewer).await?; // Write 3
// No overwrite possible — WORM semantics
4. Clear Human Interface
Review requests are formatted for readability:
┌─────────────────────────────────────────────────────────────┐
│ HUMAN REVIEW REQUEST │
├─────────────────────────────────────────────────────────────┤
│ ID: change-abc123
│ Agent: kernel-builder
│ Time: 2026-07-25 14:23:45 UTC
│ Status: ⏳ AWAITING REVIEW
├─────────────────────────────────────────────────────────────┤
│ DESCRIPTION:
│ Add phase 4 loop invariant proof
├─────────────────────────────────────────────────────────────┤
│ EVIDENCE:
│ https://github.com/snapkittywest/proof-link/phase4-inv
├─────────────────────────────────────────────────────────────┤
│ FILES MODIFIED: 3
└─────────────────────────────────────────────────────────────┘
Building and Testing
cd seb/human_touch
# Build
cargo build --release
# Run tests
cargo test -- --nocapture
# Run interactive
cargo run -- --verbose
# Run daemon
cargo run -- --daemon --webhook-port 8080
Success Criteria
- Tokio event loop compiles and runs
- Pending changes queued and formatted for human review
- Human approval required for ALL commits
- Commits tagged with human name + timestamp
- Zero auto-commits (all require human signature)
- Clear audit trail of who approved what
- WORM-sealed audit log (append-only)
- Natural language prompts (not technical jargon)
- Async non-blocking architecture
- Integration points defined
File Structure
seb/human_touch/
├── Cargo.toml # Project manifest
├── src/
│ ├── main.rs # Entry point + CLI
│ ├── review_queue.rs # Queue management
│ ├── commit_gateway.rs # Git + approval verification
│ └── audit_log.rs # WORM audit trail
├── tests/ # Integration tests
└── README.md # This file
Future Enhancements
- Webhook Server - Full HTTP endpoint for agent submission
- Web Dashboard - Real-time review queue UI
- Notification System - Slack/email alerts for pending reviews
- Policy Engine - Automated approvals for low-risk changes
- Multi-Reviewer - Require N approvals for sensitive changes
- IPFS Integration - Store audit trail on IPFS for immutability
- Blockchain Sealing - Record audit hashes on blockchain
- Performance Metrics - Track review times, approval rates
References
Status: ✅ Implementation Complete
Gate: Human-Touch v1.0.0
Date: 2026-07-25
No code lands without human touch.