feat(ledger): add append-only double-entry engine

The Lightning bridge is modelled as the boundary with the outside
world and is the one account permitted to go negative; its negative
balance is exactly what is owed to players inside the system. All
other accounts are floored at zero by both the application and a
database trigger.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

pkg/ledger/property_test.go

@@ -0,0 +1,117 @@
+package ledger_test
+
+import (
+	"context"
+	"errors"
+	"math/rand"
+	"testing"
+
+	"github.com/drjones/quantum-arcade/pkg/ledger"
+)
+
+// Across a long run of random transfers, bets, and payouts, total value must
+// never change and no player balance may go negative. This is the property that
+// makes end-of-night settlement trustworthy.
+func TestRandomActivityConservesValue(t *testing.T) {
+	l := ledger.New(testPool(t))
+	ctx := context.Background()
+
+	house, err := l.AccountByName(ctx, "house_pot")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	const players = 8
+	ids := make([]int64, players)
+	for i := range ids {
+		id, err := l.EnsurePlayer(ctx, uniqueKey(t, string(rune('a'+i))))
+		if err != nil {
+			t.Fatal(err)
+		}
+		ids[i] = id
+		if _, err := l.Deposit(ctx, id, 100_000); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	before, err := l.TotalIssued(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rng := rand.New(rand.NewSource(1))
+	roundID := int64(0)
+	for i := 0; i < 400; i++ {
+		amt := int64(rng.Intn(5000) + 1)
+		player := ids[rng.Intn(players)]
+
+		var err error
+		switch rng.Intn(3) {
+		case 0: // peer transfer
+			other := ids[rng.Intn(players)]
+			if other == player {
+				continue
+			}
+			_, err = l.Transfer(ctx, player, other, amt)
+		case 1: // bet: player pays the house
+			roundID++
+			r := roundID
+			_, err = l.Post(ctx, "bet", &r, []ledger.Posting{
+				{AccountID: player, AmountMsat: -amt},
+				{AccountID: house, AmountMsat: amt},
+			})
+		case 2: // payout: house pays the player
+			roundID++
+			r := roundID
+			_, err = l.Post(ctx, "payout", &r, []ledger.Posting{
+				{AccountID: house, AmountMsat: -amt},
+				{AccountID: player, AmountMsat: amt},
+			})
+		}
+
+		// Running out of funds is a legitimate outcome; nothing else is.
+		if err != nil && !errors.Is(err, ledger.ErrInsufficientFunds) {
+			t.Fatalf("iteration %d: %v", i, err)
+		}
+	}
+
+	after, err := l.TotalIssued(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if before != after {
+		t.Fatalf("value not conserved: %d -> %d", before, after)
+	}
+
+	for _, id := range ids {
+		bal, err := l.Balance(ctx, id)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if bal < 0 {
+			t.Fatalf("account %d went negative: %d", id, bal)
+		}
+	}
+}
+
+// Every transaction sums to zero, so the sum across all accounts including the
+// external bridge must be exactly zero at all times.
+func TestBooksAlwaysBalanceToZero(t *testing.T) {
+	l := ledger.New(testPool(t))
+	ctx := context.Background()
+
+	p, err := l.EnsurePlayer(ctx, uniqueKey(t, "p"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := l.Deposit(ctx, p, 7_777); err != nil {
+		t.Fatal(err)
+	}
+	total, err := l.ConservationCheck(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if total != 0 {
+		t.Fatalf("books do not balance: total across all accounts = %d", total)
+	}
+}