ConvergeLedger (Converge Ledger v0.1.2)

View Source

Append-only shared context store for Converge.

This service is derivative, not authoritative:

  • It remembers what already happened
  • It never decides or coordinates convergence
  • It may lose data (the Rust engine can regenerate)
  • It never mutates or rewrites history

The Rust engine remains the single semantic authority.

API

The minimal API is exposed via gRPC:

  • Append(context_id, key, payload) - Add an entry
  • Get(context_id) - Retrieve all entries
  • Snapshot(context_id) - Create a portable snapshot
  • Load(context_id, blob) - Restore from a snapshot
  • Watch(context_id) - Stream new entries (optional)

Non-Goals

This service explicitly does NOT support:

  • Conditional updates
  • Transactions across contexts
  • Locks
  • Conflict resolution
  • Branching
  • Deletes

If you need any of these, the design is wrong.

Usage

The service starts automatically when the application starts. Connect via gRPC on port 50051 (or GRPC_PORT env var).

# Local Elixir API (for testing)
{:ok, entry} = ConvergeLedger.append("my-context", "facts", payload)
{:ok, entries, seq} = ConvergeLedger.get("my-context")
{:ok, blob, seq, meta} = ConvergeLedger.snapshot("my-context")
{:ok, count, seq} = ConvergeLedger.load("my-context", blob)

Summary

Functions

Appends an entry to a context.

Gets the current sequence number for a context.

Gets entries from a context.

Loads a context from a snapshot blob.

Creates a snapshot of the entire context.

Functions

append(context_id, key, payload, metadata \\ %{})

Appends an entry to a context.

Returns {:ok, entry} with the full entry including assigned sequence number.

current_sequence(context_id)

Gets the current sequence number for a context.

Returns {:ok, sequence}.

get(context_id, opts \\ [])

Gets entries from a context.

Options:

  • :key - filter by context key
  • :after_sequence - only entries with sequence > this value
  • :limit - maximum number of entries to return

Returns {:ok, entries, latest_sequence}.

load(context_id, snapshot_blob, fail_if_exists \\ false)

Loads a context from a snapshot blob.

If fail_if_exists is true, returns an error if the context already has entries.

Returns {:ok, entries_restored, latest_sequence}.

snapshot(context_id)

Creates a snapshot of the entire context.

Returns {:ok, snapshot_blob, sequence, metadata}.