BEGIN  →  WAL JOURNAL  →  VERIFY  →  SANDBOX EXEC  →  COMMIT / ROLLBACK / COMPENSATE

              AGENT TRANSACTION LIFECYCLE
                         │
                         ▼
        ┌──────────────────────────────────┐
        │  WAL Journal (.ketan/journal)   │
        │  TX_BEGIN → TX_EFFECT → COMMIT   │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  Dual-Ledger (.ketan/ledger)    │
        │  Hash-Chained State Commitment   │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  ShadowFS (.ketan/snapshots)    │
        │  Manifest & Blob Storage         │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  Effect Contract Engine          │
        │  Pre/Postcondition Verification  │
        └──────────────────────────────────┘

graph TD
    subgraph AgentLayer [" 🤖 Agent Execution Layer "]
        LLM["LLM Agent Loop
        OpenAI • Claude • LangGraph • AutoGen"]
        MCP["🔌 FastMCP Server
        Claude Code Integration"]
        Wrapper["🛡️ KetanAgentWrapper
        Tool Call Interceptor"]
        LLM -->|Tool Call| Wrapper
        MCP -->|Safe Tool Execution| Wrapper
    end

    subgraph CoreEngine [" 🪔 Ketan-OS Transactional Substrate "]
        Harness["🪔 KetanHarness
        Thread-Safe Coordinator"]

        subgraph WALJournal [" Durable WAL Journal "]
            Journal["📝 TransactionJournal
            .ketan/journal.jsonl Persistence"]
        end

        subgraph PreFlight [" Pre-Flight Guard Layer "]
            Verifier["🛡️ InvariantVerifier
            Canonical Path Confinement
            Symlink Guard + AST & Safety Rules"]
        end

        subgraph Sandboxes [" Execution Sandbox Engines "]
            Sandbox["📦 Local / Docker Sandbox Engine
            Path Confinement & Container Isolation"]
        end

        subgraph StorageLedger [" Dual-Ledger Substrate "]
            Ledger["📋 KetanLedger
            Checkpoint & Reversibility Registry"]
            ShadowFS["💾 KetanShadowFS
            Content-Addressed Workspace Recovery"]
            Ledger --> ShadowFS
        end

        subgraph Cognition [" State Belief Layer "]
            Epistemic["🧠 EpistemicBeliefEngine
            Runtime Fact Store &
            Prompt Contradiction Pruning"]
        end

        subgraph CTGSubsystem [" Causal Provenance Engine "]
            CTG["🧬 KetanTraceGraph
            Causal Execution Provenance DAG"]
            RCA["🔍 Provenance Analyzer
            Execution Lineage Explanation"]
            CTG --> RCA
        end

        subgraph TimeTravel [" Transaction Recovery & Compensation "]
            Rollback["⏱️ Rollback Controller
            Workspace State Reversion"]
            CompDrivers["🔄 System Compensation Drivers
            Git & SQL Inverse Actions"]
            Counterfactual["💡 Counterfactual Engine
            Diagnostic Hint Injector"]
            Rollback --> CompDrivers
            CompDrivers --> Counterfactual
        end
    end

    Wrapper -->|"① Intercept"| Harness
    Harness -->|"② WAL Record TX_BEGIN"| Journal
    Journal -->|"③ Pre-flight"| Verifier
    Verifier -->|"④ Pre-Flight Pass"| Epistemic
    Epistemic -->|"⑤ Checkpoint"| ShadowFS
    ShadowFS -->|"⑥ Sandbox Exec"| Sandbox
    Sandbox -->|"⑦ Execute Tool"| Execution["⚙️ Tool Execution"]

    Verifier -.->|Path / Syntax / Safety Fail| Rollback
    Execution -->|Crash / Exception| Rollback

    Execution -->|Success| Commit["🟢 WAL Commit & Record"]
    Commit --> CTG
    Commit --> Ledger

    Rollback -->|"⑧ Revert Workspace"| ShadowFS
    Rollback -->|"⑨ Execute Compensations"| CompDrivers
    Rollback -->|"⑩ Record Failure Node"| CTG
    Counterfactual -->|"⑪ Inject Hint"| LLM

    classDef agent    fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b
    classDef core     fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0c4a6e
    classDef storage  fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#064e3b
    classDef rollback fill:#ffe4e6,stroke:#e11d48,stroke-width:2px,color:#881337
    classDef ctg      fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
    classDef exec     fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d

    class LLM,Wrapper,MCP agent
    class Harness,Verifier,Epistemic,Journal,Sandbox core
    class Ledger,ShadowFS storage
    class Rollback,CompDrivers,Counterfactual rollback
    class CTG,RCA ctg
    class Execution,Commit exec

from ketan import KetanHarness, KetanAgentWrapper

# 1. Initialize Ketan-OS for your project workspace
harness = KetanHarness(workspace_dir="./my_project")
wrapper = KetanAgentWrapper(harness)

# 2. Wrap any tool with transactional protection
def write_code(args):
    with open(args["filepath"], "w") as f:
        f.write(args["content"])
    return "File written"

safe_write = wrapper.wrap_tool("write_file", write_code)

# 3. Execute — Ketan-OS handles snapshot, pre-flight, rollback automatically
result = safe_write(
    tool_args={"filepath": "main.py", "content": "def run():\n    return 42\n"},
    prompt_stack=[{"role": "user", "content": "Create main function"}]
)
print(result)
# → {"success": True, "result": "File written", "hint": ""}
# If content had a syntax error → {"success": False, "hint": "Fix SyntaxError on line 1..."}
# → workspace auto-rolled back cleanly

git clone https://github.com/umang-algo/ketan-os.git
cd ketan-os
uv pip install -e .

{
  "mcpServers": {
    "ketan-os": {
      "command": "python",
      "args": ["-m", "ketan.mcp.server", "--workspace", "/absolute/path/to/your/project"]
    }
  }
}

# Run unit test suite
uv run pytest tests/

# Run performance benchmark suite
uv run python examples/benchmark_ketan_performance.py