caelum0x 9b4e470dce feat(sdk): rust-client had no credential story at all; add CloseCard to both SDKs
services/gateway's tenantauth interceptor defaults
RATION_GATEWAY_REQUIRE_TENANT_AUTH to true, but sdk/rust/ration-client
had zero way to attach any credential — no WithAPIKey/WithBearerToken
equivalent of what sdk/go/ration got in round 3. Every RPC the Rust SDK
made against a default-config gateway failed Unauthenticated; its own
doc.go-equivalent example never worked. Added CredentialInterceptor
(tonic Interceptor) plus Client::connect_with_api_key/
connect_with_bearer_token and from_channel_with_api_key/
from_channel_with_bearer_token, mirroring the Go SDK's dial-option
pattern.

Also closed a smaller parity gap found along the way: CloseCard
(round 11) was wired into gateway.proto/CLI but never added to either
official SDK, so an external platform customer importing sdk/go/ration
or sdk/rust/ration-client had no way to shut off a leaked/offboarded
card's spending via the SDK itself. Added Client.CloseCard (Go) and
Client::close_card (Rust).

Verified live against the real bare-metal 8-service stack
(scripts/start-individually.sh): a throwaway Go program using the real
sdk/go/ration module (replace-directive to this repo) issued a card
through the gateway, closed it, confirmed idempotent re-close, confirmed
AdjustCardLimit now correctly rejects the closed card, and confirmed an
unknown card_id fails the same way GetCard/AdjustCardLimit already do.
`ration status` showed the full $100 hold released back to Available.
Separately, a throwaway Rust binary against the real ration-client
crate (path dependency) first proved the pre-fix gap live (Client::connect
with zero credential against the real auth-required gateway ->
Unauthenticated), then used connect_with_api_key to run the identical
issue/close/idempotent-close/adjust-limit-rejected/unknown-card cycle
successfully, independently confirmed via `ration status` that the
$75 hold was released.

make build (full Rust+Go+SDK), go vet across every Go module, cargo
build --release, cargo clippy, cargo fmt all clean, 0 regressions.
cargo test for ration-client remains pre-existing-broken only on its
FakeGateway test fixture missing close_card/get_dashboard_snapshot
(round 3's already-flagged, intentionally-not-fixed gap, per the
no-test-infra-work standing rule) — unaffected by this change since
make build never runs cargo test for this crate.
2026-10-29 12:19:19 +03:00

Ration

Ration

License Go Rust

Agentic multi-tenant spend controller for the Airwallex Agentic Banking Hackathon — Starter Kit 5: Platform Spend Controller (Multi-Tenant Platforms track).

Issue customer cards and ration bridge funding when deposits arrive late.

No web dashboard. This is a systems project: a Rust ledger core backed by a hand-rolled C write-ahead log, a Go gateway that owns the Airwallex integration, a Go agent loop that makes the actual rationing decisions (policy rules + an LLM for judgment calls), and a terminal UI for judges to watch it work live.

Engineering standard: this is built to the bar of production fintech infrastructure, not hackathon scaffolding — real crash-safety (see the WAL recovery tests), a hard-rule money-safety invariant the LLM can never override, and a scale-out roadmap (service decomposition, observability, infra-as-code, formal verification, fuzzing/chaos testing — see docs/SCALE-EXPANSION.md) aimed at unicorn-scale production use, not a weekend demo.

Architecture

                    ┌─────────────────────┐
                    │   tui / cli (Go)     │  terminal dashboard + demo driver
                    └──────────┬───────────┘
                               │ gRPC
                    ┌──────────▼───────────┐       ┌────────────────────┐
  Airwallex API <──►│   gateway (Go)        │──────►│  agent (Go)         │
  (mock or live)    │  issuing/global accts │ gRPC  │  policy + LLM loop  │
                    │  webhooks, multi-tenant│◄──────│  tool-calling        │
                    └──────────┬───────────┘       └────────────────────┘
                               │ gRPC
                    ┌──────────▼───────────┐
                    │  ledger-core (Rust)   │  authoritative balances,
                    │  double-entry, reserve │  deposits, reserve floor
                    │  floor enforcement     │
                    └──────────┬───────────┘
                               │ FFI
                    ┌──────────▼───────────┐
                    │  wal (C)              │  crash-safe append log +
                    │  write-ahead log       │  recovery, fsync-correct
                    └───────────────────────┘

See docs/ARCHITECTURE.md for the full design, docs/AGENT-DESIGN.md for the agent/policy design, and docs/AIRWALLEX-SETUP.md for sandbox access status.

Services

Service Language Role
services/wal C Crash-safe write-ahead log: append, fsync, recover.
services/ledger-core Rust Double-entry ledger, reserve-floor enforcement, deposit tracking. gRPC server over the C WAL.
services/gateway Go Airwallex Issuing/Global Accounts/webhooks client (mock + live), multi-tenant routing, fronts ledger-core.
services/agent Go Agentic loop: watches late deposits, decides card issuance / bridge rationing, calls an LLM for non-deterministic judgment calls, executes via gateway.
services/tui Go (Bubble Tea) Terminal dashboard: tenants, deposits, cards, live agent activity feed.
services/cli Go Operator CLI: seed demo tenants, simulate deposits, force late-deposit scenarios for judging.
proto/ Protobuf Wire contracts shared by every service.

Quickstart

make proto          # generate Go stubs from proto/
make build           # build all services
make run-demo         # starts wal-backed ledger-core, gateway (mock Airwallex), agent, seeds 3 tenants
./bin/tui              # watch it live in a second terminal

Airwallex mode

AIRWALLEX_MODE=mock (default) runs entirely against an in-process fake that mirrors the real Issuing/Global Accounts/webhook contracts byte-for-byte so flipping to AIRWALLEX_MODE=live with real sandbox credentials is a one-line env change, not a rewrite. Sandbox platform access is pending organizer approval — see docs/AIRWALLEX-SETUP.md.

What integration actually found

Six services were built independently against a pinned proto/architecture spec, then integrated. Integration is where real bugs show up — compile errors are the easy part. Three were found and fixed, not papered over:

  1. A proto-regeneration collision that silently shadowed checked-in generated code.
  2. ledger-core and every client disagreeing on which env var carried the listen address — the stack would never actually connect with default config.
  3. The one that mattered: MarkDepositReceived updated deposit status but never credited the ledger, so every tenant's balance was permanently stuck at 0. Reserve-floor headroom was always negative, so the bridge-funding policy could only ever decline — the entire agentic rationing feature, the actual point of this submission, could never produce a real grant. Fixed at the ledger level with an idempotent mark-and-credit in a single WAL frame, covered by new tests.

The full, reproducible demo run (seed → simulate a late deposit → agent grants a partial bridge with a computed rationale → a second request correctly declines once the 24h velocity cap engages) is documented in docs/DEMO-SCRIPT.md. The submission writeup is in docs/SUBMISSION.md.

Contributing

Each service is its own module with its own tests — run the relevant one (go test ./... in a Go service, cargo test in ledger-core, make test in services/wal) before opening a PR. Money-path changes (anything that touches ledger-core::ledger or services/gateway/internal/bridge) need a test that exercises the reserve-floor invariant — see docs/AGENT-DESIGN.md for the exact rules it must never violate.

License

Apache-2.0 — see LICENSE.

Description
Agentic multi-tenant spend controller for the Airwallex hackathon — Rust/C/Go, no web frontend
Readme Apache-2.0 13 MiB
Languages
Go 67.5%
Rust 20.3%
HCL 4.6%
C 3.3%
Shell 2.4%
Other 1.9%