Converge Ledger

An optional, distributed, append-only runtime substrate for Converge

⸻

What This Is

Converge Ledger is a supporting runtime component for the Converge engine.

It exists to externalize ephemeral context from a running Converge process when scale, distribution, or observability demands it — without ever becoming a source of semantic truth.

Convergence happens in Rust. Anything distributed only exists to remember what already happened.

The ledger does not decide, coordinate, or validate anything. It cannot cause convergence. It cannot break convergence.

If Converge Core did not exist, this system would be meaningless.

⸻

What This Is Not

To avoid architectural drift, this is explicit:

• ❌ Not a coordination layer
• ❌ Not a workflow engine
• ❌ Not an agent communication bus
• ❌ Not a CRDT for reasoning
• ❌ Not a replacement for Converge Core
• ❌ Not required for correctness

Converge Ledger is derivative, optional, and replaceable.

⸻

Why This Exists

Converge Core is designed around:

• Single-root intent
• Append-only semantic context
• Deterministic convergence
• Explicit authority
• Provable invariants

In many cases, a single Rust process is sufficient.

However, some deployments benefit from:

• Large contexts that exceed process memory
• Multiple engine instances observing the same context
• Real-time inspection and debugging
• Fast recovery after restart
• Horizontal scaling at the job level

Converge Ledger exists only to support these cases — as a runtime substrate, not a conceptual pillar.

⸻

Design Principle

The ledger never knows why something happened. It only knows that it happened.

All meaning lives in Converge Core.

⸻

The Data Model

The ledger stores append-only entries, grouped by context ID.

Each entry is:

• Sequential
• Immutable
• Timestamped
• Typed (fact, proposal, eval, trace, etc.)
• Opaque to the ledger itself

┌─────────────────────────────────────────────────────────┐
│ Context: growth-strategy-001                             │
├──────────┬────────────┬─────────────────────────────────┤
│ seq=1    │ facts      │ market_size: 2.4B               │
│ seq=2    │ intents    │ objective: increase_demand      │
│ seq=3    │ traces     │ agent:analyst started           │
│ seq=4    │ proposals  │ strategy: partnership_model    │
│ seq=5    │ evals      │ confidence: 0.73                │
│   ⋮      │    ⋮       │        ⋮                        │
└─────────────────────────────────────────────────────────┘

There are no updates, deletes, or rewrites.

⸻

Consistency Model

• Single-writer per root intent (the Converge engine)
• Multiple readers (other engines, observers, tools)
• Append-only semantics guarantee:
  • No conflicts
  • No merge logic
  • No semantic ambiguity

Replication exists to mirror state, not to resolve meaning.

⸻

Why Elixir / OTP

Converge Ledger is implemented in Elixir on OTP because it provides:

Lightweight Concurrency

Millions of isolated processes with minimal overhead.

Fault Isolation

Failures restart locally without corrupting state.

Distribution

Node discovery, clustering, and replication are built-in.

In-Memory Performance

Reads and writes operate at microsecond scale.

Operational Simplicity

This is solved infrastructure — not a research problem.

⸻

Durability Model

The ledger is not authoritative.

• Losing ledger data must not break correctness
• Converge Core can always regenerate context
• Persistence exists for operational convenience, not truth

Mnesia supports:

• In-memory tables (ram_copies)
• Disk-backed tables (disc_copies)

Use durability when needed — but never rely on it for semantics.

⸻

API (Minimal by Design)

The ledger exposes exactly five operations:

Deliberately missing:

• Updates
• Deletes
• Transactions
• Branching
• Conditional writes

If you need those, you're using the wrong system.

⸻

Architecture

┌─────────────────────────────────────────────────────────────┐
│               Converge Core (Rust – Authority)               │
│                                                             │
│  • Root intent                                               │
│  • Convergence logic                                         │
│  • Invariant enforcement                                    │
│  • HITL gating                                               │
└───────────────────────────────┬─────────────────────────────┘
                                │ gRPC
                                ▼
┌─────────────────────────────────────────────────────────────┐
│             Converge Ledger (Elixir – Substrate)              │
│                                                             │
│  • Append-only storage                                      │
│  • Replication & catch-up                                   │
│  • Watch streams                                            │
│  • Snapshot / restore                                       │
│                                                             │
│   No decisions • No validation • No authority               │
└─────────────────────────────────────────────────────────────┘

⸻

When to Use This

Use Converge Ledger when you need:

• Distributed observation of a running convergence
• Fast restart without recomputation
• External tooling (debuggers, dashboards)
• Large or long-running contexts
• Multi-node execution per job

Do not use it:

• As a replacement for Converge Core
• As an agent communication layer
• As a general-purpose database

⸻

The Contract

This repository obeys one rule:

Nothing in this system may influence convergence semantics.

If a proposed change violates that rule, it does not belong here.

⸻

Documentation

• ARCHITECTURE.md — Detailed architecture, design decisions, and implementation details
• CONTRIBUTING.md — Development setup, testing requirements, and contribution guidelines
• LICENSE — MIT License

⸻

License

MIT

⸻

Final Note

Converge is built on the idea that systems should halt, explain themselves, and resume safely.

This ledger exists only to make that practical at scale — never to make it ambiguous.