WIP snapshot before drive cleanup 2026-10-03

This commit is contained in:
George Lambert 2026-10-03 23:02:02 -04:00
commit e666e7bf3c
3 changed files with 2828 additions and 1 deletions

View file

@ -4,3 +4,10 @@
**Step:** 1
Prepaid cents, credits, usage, and payments persist in `zappier-account-balance` (`books.json`). zappier-edge `balanceCents` is a cache filled from the books reply. Tests without NATS/HTTP books still mutate the cache so unit tests stay hermetic.
## Addendum (2026-10-03, D006)
Durable prepaid/credits/usage/payments store is shared **libSQL**, not per-process
`books.json` or per-host `billing.db`. Single writer path still required. Edge
`balanceCents` remains a cache. Lab `books.json` / `billing.db` are migration sources.

View file

@ -0,0 +1,39 @@
# D006 — Business data in libSQL; JetStream only for work
**Status:** accepted
**Step:** 6
**Date:** 2026-10-03
Launch topology is **3–5 machines** (gateway, bridge, delivery, and related planes). Shared business state must not live as per-host SQLite files.
## Decision
1. **System of record for business / accounting / customers / pricing** is **libSQL** (Turso’s SQLite fork; server mode or hosted). That includes:
- customers, segments, tiers, balances, Stripe / PO metadata
- pricing and channel×segment rate cards
- invoices and invoice lines
- metered usage ledger (`usage_entries` and its append-only hash chain)
- other accounting and CRM-style records for the Zapier/Verae edge stack
2. **NATS JetStream** is used **as necessary** for multi-host **work distribution** (job queues, competing consumers, retries, durable event fans that are not the money ledger). Examples: `ZAPIER_JOBS`, worker pull/ack, bridge task streams.
3. **Core NATS (ephemeral)** remains mandatory for Verae timestamp **job-complete / jobId** notifications (`verae.ts.completed`, `verae.ts.receipt`). Those must **not** move to JetStream.
4. **Timestamping-svc Go** `blockchain.db` and other Go timestamping SQLite files stay on that service; this decision does not relocate them.
## Relationship to earlier decisions
- **D001** (single prepaid writer) still holds: one logical writer path for prepaid/credits. The durable store for that path becomes **libSQL**, not per-process `books.json` or a private `billing.db` on each machine. Edge `balanceCents` may remain a cache filled from the billing/libSQL service.
- Lab `billing.db` / `zappier.db` on 138 are the current single-host stand-in; migrate that schema into shared libSQL before splitting planes across hosts.
## Non-goals
- JetStream as the customer/balance/invoice/pricing database
- Litestream as a multi-writer fabric (Litestream remains backup/DR for a primary if used)
- Per-machine copies of customer or pricing tables
## Implementation sketch
- Keep repositories behind a small DB interface; swap better-sqlite3 / modernc file opens for libSQL client when the shared server is up.
- One billing writer path owns usage hash-chain appends (`BEGIN`-style sequencing).
- Gateway/bridge/delivery call billing APIs or the shared libSQL endpoint; they do not each open a local billing file for production.

10
decisions/index.md Normal file
View file

@ -0,0 +1,10 @@
# Decisions
6 files in this book.
- [D001-prepaid-sot.md](D001-prepaid-sot.md)
- [D002-identity.md](D002-identity.md)
- [D003-public-doors.md](D003-public-doors.md)
- [D004-leaf-accounts.md](D004-leaf-accounts.md)
- [D005-fleet-local-first.md](D005-fleet-local-first.md)
- [D006-libsql-business-jetstream-work.md](D006-libsql-business-jetstream-work.md)