Round fourteen: “how does anything else talk to it?”

// a dead peer with no traffic is indistinguishable from an idle one.
// without keepalive, a half-open connection can sit for HOURS.
TCP_KEEPIDLE  = 30   // start probing after 30 s idle
TCP_KEEPINTVL = 10   // probe every 10 s
TCP_KEEPCNT   = 3    // 3 failures ⇒ dead. detected in ~60 s.

// Nagle batches small writes to save packets, adding up to 40 ms.
// on a request/response path that is pure added latency.
TCP_NODELAY = true

// and a connect timeout, because the OS default can be over a minute,
// which is far longer than any budget we set in Part 8.
connectTimeoutMs = 2000

// the four call types, and where each is used here
service Ledger {
  // 1. unary: the overwhelming majority. post, query, resolve.
  rpc Post(PostRequest) returns (PostResponse);

  // 2. server streaming: a large export without buffering it all.
  rpc StreamEntries(StreamRequest) returns (stream Entry);

  // 3. client streaming: bulk upload, e.g. a payroll batch.
  rpc PostBatch(stream PostRequest) returns (BatchSummary);

  // 4. bidirectional: rare internally. used by the card authoriser
  //    to keep a warm channel with continuous health signalling.
  rpc AuthChannel(stream AuthMsg) returns (stream AuthReply);
}

// the fix: a bounded per-connection queue with an explicit policy for
// what to do when it fills. never an unbounded buffer.
class BalanceFeed {
  private queue: Update[] = [];
  private static MAX = 32;

  push(u: Update) {
    if (this.queue.length >= BalanceFeed.MAX) {
      // for a BALANCE, only the latest value matters: collapse.
      // this is the key insight: the semantics of the data decide
      // the shedding policy.
      this.queue = [this.queue[0], u];
      this.markResyncNeeded();   // tell the client to refetch
      return;
    }
    this.queue.push(u);
  }
}

// SSE with resumption. the id: field is what makes reconnect lossless,
// and we already have a perfect monotonic id: the entry id from Part 1.
res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'X-Accel-Buffering': 'no'    // stop nginx buffering the stream
});

// the browser sends Last-Event-ID on reconnect, so we resume exactly.
const resumeFrom = req.headers['last-event-id'] ?? '0';

for await (const e of entriesSince(accountId, BigInt(resumeFrom))) {
  res.write(`id: ${e.id}\n`);
  res.write(`event: balance\n`);
  res.write(`data: ${JSON.stringify({ balance: e.balanceAfter.toString() })}\n\n`);
}

service Ledger {
  rpc Post(PostRequest) returns (PostResponse);
  rpc GetBalance(BalanceRequest) returns (BalanceResponse);
  rpc PlaceHold(HoldRequest) returns (HoldResponse);
  rpc ResolveHold(ResolveHoldRequest) returns (PostResponse);
  rpc GetJournal(JournalRequest) returns (Journal);
}

message PostRequest {
  // REQUIRED. the caller's own natural key for this intent.
  // "loan-disb-{loanId}", "accrual-{loanId}-{date}". see Part 5.
  string idempotency_key = 1;

  // what KIND of business event. drives GL mapping and reporting,
  // and it is an enum so a typo is a compile error.
  JournalKind kind = 2;

  // the entries. the ledger validates they sum to zero PER CURRENCY
  // and REFUSES otherwise. a caller bug cannot break the invariant.
  repeated EntrySpec entries = 3;

  // opaque to the ledger. stored, indexed, never interpreted.
  map<string, string> metadata = 4;

  // links a correction to what it corrects. Part 10.
  optional string reverses_journal_id = 5;
}

message EntrySpec {
  string account_id = 1;
  int64  amount_minor = 2;    // signed. negative = debit. int64, exact.
  string currency = 3;
  // the floor for THIS entry: 0 normally, negative for overdraft.
  // the ledger enforces it inside the insert, per Part 1.
  optional int64 min_balance_minor = 4;
}

// LOANS SERVICE owns: eligibility, pricing, schedule, product rules.
// LEDGER owns: that the entries balance and are durably recorded.
const res = await ledger.post({
  idempotencyKey: `loan-disb-${loan.id}`,   // natural, one per loan
  kind: JournalKind.LOAN_DISBURSEMENT,
  entries: [
    { accountId: `loan_receivable:${loan.id}`, amountMinor: -50_000_000n,
      currency: 'NGN' },
    { accountId: customer.ngnWalletId,          amountMinor:  49_500_000n,
      currency: 'NGN' },
    { accountId: 'fee_income:origination',      amountMinor:     500_000n,
      currency: 'NGN' }
  ],
  metadata: { loan_id: loan.id, product: 'salary_advance', tenor_days: '30' }
});
// if the loans service has a bug and these do not sum to zero,
// the ledger returns INVALID_ARGUMENT and writes nothing.

// a sweep consumes the Part 4 event stream and reacts to credits.
// the floor is the whole ethics of the feature: never take a customer
// to zero, or they cannot eat and they default anyway.
async function onCredit(e: LedgerEvent) {
  const loan = await loans.activeFor(e.accountId);
  if (!loan || !loan.sweepConsented) return;

  const available = await ledger.getBalance(e.accountId);
  const sweepable = available - loan.protectedFloorMinor;   // e.g. ₦5,000
  if (sweepable <= 0n) return;

  const amount = min(sweepable, loan.outstandingMinor, loan.maxSweepPerEvent);

  await ledger.post({
    // the key includes the triggering entry, so a redelivered event
    // cannot sweep twice.
    idempotencyKey: `sweep-${loan.id}-${e.entryId}`,
    kind: JournalKind.LOAN_REPAYMENT,
    entries: allocateRepayment(loan, amount)   // fees → interest → principal
  });
}

-- the ledger's own check, inside the posting transaction.
-- effective_floor = MAX(requested, actually_granted)
-- both are negative, so MAX is the more conservative.
WITH facility AS (
  SELECT COALESCE(-limit_amount, 0) AS granted_floor
    FROM overdraft_facilities
   WHERE account_id = $acct
     AND state = 'active'
     AND (expires_at IS NULL OR expires_at > now())
     -- the kind gate from Part 5: this transaction type may draw it
     AND $kind = ANY(allowed_kinds)
)
INSERT INTO entries (journal_id, account_id, amount, currency)
SELECT $jid, $acct, $amt, $ccy
  FROM facility f
 WHERE (SELECT COALESCE(SUM(amount),0) FROM entries
          WHERE account_id = $acct AND currency = $ccy) + $amt
       >= GREATEST($requested_floor, f.granted_floor);

// accrual: the key carries the date, so a re-run posts nothing twice.
await ledger.post({
  idempotencyKey: `sav-accrual-${account.id}-${date}`,
  kind: JournalKind.INTEREST_ACCRUAL,
  entries: [
    { accountId: 'interest_expense',               amountMinor: -21_917n, currency: 'NGN' },
    { accountId: `interest_payable:${account.id}`, amountMinor:  21_917n, currency: 'NGN' }
  ]
});

// capitalisation: monthly, moving accrued interest into spendable money.
await ledger.post({
  idempotencyKey: `sav-capitalise-${account.id}-${yearMonth}`,
  kind: JournalKind.INTEREST_CAPITALISATION,
  entries: [
    { accountId: `interest_payable:${account.id}`, amountMinor: -657_510n, currency: 'NGN' },
    { accountId: account.walletId,                  amountMinor:  657_510n, currency: 'NGN' }
  ]
});

// an override is a SIGNED, SCOPED, SINGLE-USE, EXPIRING grant.
// it is never a boolean flag on a request, because a boolean can be
// set by anyone who can call the API.
interface LimitOverride {
  overrideId: string;
  accountId: string;
  limitType: 'per_transaction' | 'velocity' | 'daily_cumulative';
  maxAmountMinor: bigint;      // bounded. not unlimited.
  currency: string;
  grantedBy: string;           // 'customer:step_up' | 'analyst:u-441'
  approvedBy?: string;         // four-eyes where required
  reason: string;              // recorded for audit, always
  expiresAt: Date;             // minutes, not days
  singleUse: boolean;
  // signed by the granting service so the ledger can verify it
  // without trusting the caller that presented it.
  signature: string;
}

// authorisation: what this identity may do, as explicit policy.
// note it is scoped to ACCOUNT KINDS, not just to methods.
{
  "spiffe://bank/ns/prod/sa/loans": {
    "ledger.Post": {
      "kinds": ["LOAN_DISBURSEMENT", "LOAN_REPAYMENT", "INTEREST_ACCRUAL"],
      // may touch loan accounts and customer wallets, and nothing else.
      "account_kinds": ["loan_receivable", "interest_receivable",
                        "customer_wallet", "fee_income"],
      "max_amount_minor": 500000000,     // ₦5m per posting
      "rate_limit_per_sec": 2000
    },
    "ledger.GetBalance": { "account_kinds": ["customer_wallet"] }
  }
}

// the SDK makes the correct thing the easy thing
const ledger = new LedgerClient({
  identity: 'spiffe://bank/ns/prod/sa/loans',
  defaultDeadlineMs: 250,
  retry: { maxAttempts: 3, jitter: true,
           retryOn: ['UNAVAILABLE', 'DEADLINE_EXCEEDED', 'RESOURCE_EXHAUSTED'] }
});

// compile error without an idempotency key. not a runtime warning.
await ledger.post({ idempotencyKey, kind, entries });

// and it validates the sum locally first, so a caller bug surfaces
// as "entries do not balance: NGN sums to -1000" rather than as a 400.

message EntrySpec {
  string account_id = 1;
  int64  amount_minor = 2;
  string currency = 3;
  optional int64 min_balance_minor = 4;

  // removed in v2.3. the number is reserved so it can NEVER be reused
  // for a different meaning, which would silently corrupt old callers.
  reserved 5;
  reserved "legacy_floor";

  // added in v2.4, optional with a safe default.
  optional string value_date = 6;   // Part 10's second date
}