Undone

The Local-First Spatial Audit & Surgical Revert Layer for Autonomous AI Agents

1. Overview & Problem Space

Autonomous AI coding agents (Claude Code, Cursor Agent, OpenHands, Aider) perform multi-step, batch file transformations across codebases. During an extended session, an agent may modify dozens of files across multiple iterations.

When an agent introduces a defect, regression, or security leak midway through execution (e.g., at Step #8 of a 20-step refactoring chain):

• Traditional Version Control (git reset --hard) operates at the whole-tree commit level, discarding all subsequent valid modifications (the other 12 constructive steps).
• Linear Undo Buffers in standard IDEs operate strictly within single-file active memory, lacking cross-file dependency awareness and session persistence.

Undone provides an independent, content-addressed temporal audit and revert layer. Powered by Content-Addressed Storage (CAS), Eugene W. Myers' (O(ND)) Shortest Edit Script diff algorithm, and 3-Way Temporal Rebase, Undone enables surgical single-file inversions that isolate and revert a specific flawed step while preserving 100% of non-overlapping subsequent modifications.

2. 10 High-Stress Industrial Validation Matrix

To guarantee mathematical correctness and data consistency under complex refactoring operations, Undone runs a rigorous 10-scenario stress suite (verify anytime via node tests/stress_suite.js):

| Scenario | Stress Category | Core Engineering Challenge | Undone Mechanism & Test Result | Status | | :--- | :--- | :--- | :--- | :--- | | A | Pure Insertion | Inserting lines in the middle without shifting downstream line offsets | Myers (O(ND)) dynamic programming backtracking cleanly strips inserted lines with zero index drift | ✅ PASS | | B | Pure Deletion | Reverting deleted functions or blocks | Extracts target lines from CAS cryptographic snapshots and restores them at exact line ranges | ✅ PASS | | C | Multiple Disjoint Edits | Simultaneous top, middle, and bottom file changes | Generates multi-hunk inverse patches, reverting all disjoint modifications in one atomic pass | ✅ PASS | | D | Subsequent Edits in Different Regions | Step 2 introduces a port bug; Step 3 adds logging below | 3-Way Rebase inverts the port bug while 100% preserving subsequent logging modifications | ✅ PASS | | E | Subsequent Edits in Same Region | Step 2 and Step 3 modify the exact same line | Detects true overlapping collisions and injects standard 3-Way conflict markers (<<<<<<< / ======= / >>>>>>>) | ✅ PASS | | F | File Creation Revert | Step introduces an unwanted file | Inverse delta computes empty target state and safely executes physical file unlink | ✅ PASS | | G | File Deletion Restoration | Step accidentally deletes an essential source file | Resolves file's original SHA-256 blob from CAS pool and reconstructs complete source code | ✅ PASS | | H | Multi-File Dependency Breakage | Reverting auth.ts deletes verifyToken, breaking routes.ts and server.ts | AST DAG traverses reverse dependency graph, flagging both direct and transitive downstream breaks | ✅ PASS | | I | Barrel Re-Export Tracking | Symbols re-exported through barrel index.ts (export * from './db') | AST parser resolves barrel index chains, identifying indirect downstream consumer breakages | ✅ PASS | | J | 20 Consecutive Action Frames | High-frequency continuous batch agent modifications | Pure-hash ledger maintains zero-bloat state; reconstructs any byte-exact historical snapshot in < 1ms | ✅ PASS |

3. Core Architecture & Mathematical Pipeline

┌────────────────────────────────────────────────────────────────────────┐
│                        UNDONE CORE ARCHITECTURE                        │
├──────────────────────────────────┬─────────────────────────────────────┤
│  1. Content-Addressed Storage    │  2. Myers O(ND) SES Diff Engine     │
│  SHA-256 hash buckets + zstd     │  Minimal Shortest Edit Script graph │
├──────────────────────────────────┼─────────────────────────────────────┤
│  3. 3-Way Temporal Rebase Engine │  4. Bidirectional AST Graph (DAG)   │
│  Merge(CurrentTip, Target, Base) │  Forward & Reverse dependency maps  │
└──────────────────────────────────┴─────────────────────────────────────┘

3.1 3-Way Temporal Rebase Mechanics

When inverting action frame (T_k) on file (F):

• (\text{Base} = T_k.\text{newContent}) (State introduced by step (T_k))
• (\text{Target} = T_k.\text{oldContent}) (Pre-mutation state before step (T_k))
• (\text{CurrentTip} = \text{DiskContent}(F)) (Latest code containing (T_{k+1} \dots T_n))
• Rebase Solver: (\text{Result} = \text{Merge}(\text{CurrentTip}, \text{Target}, \text{Base}))
  • If non-overlapping: merges cleanly and writes verified source to disk;
  • If overlapping: emits standard 3-Way conflict blocks for human review.

3.2 Pure Hash Ledger & CAS Decoupling

• .undone/objects/xx/yyyy...: Immutable physical source object pool (compressed with zstd);
• .undone/ledger.json: Pure metadata ledger containing action frames, timestamps, agent metadata, and cryptographic oldHash / newHash pointers.

4. Quick Start & CLI Reference

4.1 Zero-Config Agent Auto-Installer (Recommended)

Automatically detects installed Claude Desktop, Cursor IDE, and Claude Code instances and configures MCP:

npx undone-ai init

4.2 Start Live Watcher Daemon

Launch the studio daemon in any repository root:

npx undone-ai watch .

Open http://localhost:4141 to access the interactive spatial studio (with 1-click switching between your live repository and the interactive tutorial sandbox).

4.3 CLI Commands

# Auto-detect and configure MCP for installed agents
npx undone-ai init

# Start background file watcher daemon & interactive studio (default port 4141)
npx undone-ai watch .

# Run standard MCP server over stdio
npx undone-ai mcp

# Wrap an active agent process (e.g. Claude Code CLI / Aider)
npx undone-ai wrap claude

# Query local CAS storage metrics and deduplication stats
npx undone-ai status

# Output chronological terminal audit trail of all recorded frames
npx undone-ai log

# Execute the 10-scenario high-stress test suite
node tests/stress_suite.js

5. Keyboard Navigation

| Key Binding | Function | | :--- | :--- | | Space | Play / Pause automated timeline playback | | ← or J | Step backward one frame | | → or L | Step forward one frame | | Esc | Dismiss modal dialogs / inspectors |

6. License

This project is licensed under the MIT License.