feat(bss-ledger): billing ledger gear, SDK, coord lease lib, and design docs

.cf-studio/config/artifacts.toml

@@ -10,6 +10,14 @@ patterns = ["gears/system"]
 reason = "Ignore 'gears/bss' parent directory — not a module, only a grouping for BSS submodules."
 patterns = ["gears/bss"]
 
+[[ignore]]
+reason = "Ignore 'gears/bss/libs' — not a module, only a grouping for shared BSS utility libraries."
+patterns = ["gears/bss/libs"]
+
+[[ignore]]
+reason = "Ignore 'coord' shared utility library (distributed-lease primitive; infrastructure crate, not an SDLC-documented product module — no PRD/DESIGN required, README-documented)."
+patterns = ["gears/bss/libs/coord/*"]
+
 [[ignore]]
 reason = "Ignore authn-resolver root module node while allowing nested plugin docs scopes."
 patterns = ["gears/system/authn-resolver"]

Cargo.toml

@@ -99,6 +99,9 @@ members = [
     "gears/system/usage-collector/plugins/noop-usage-collector-plugin",
     "gears/mini-chat/mini-chat-sdk",
     "gears/mini-chat/mini-chat",
+    "gears/bss/ledger/ledger",
+    "gears/bss/ledger/ledger-sdk",
+    "gears/bss/libs/coord",
 ]
 exclude = ["tools/fuzz"]
 resolver = "3"
@@ -283,6 +286,12 @@ resource-group-sdk = { package = "cf-gears-resource-group-sdk", version = "0.2.0
 oagw-sdk = { package = "cf-gears-oagw-sdk", version = "0.5.3", path = "gears/system/oagw/oagw-sdk" }
 usage-collector-sdk = { package = "cf-gears-usage-collector-sdk", version = "0.1.0", path = "gears/system/usage-collector/usage-collector-sdk" }
 
+# BSS gears (ported from vhp-core)
+bss-ledger-sdk = { path = "gears/bss/ledger/ledger-sdk" }
+coord = { path = "gears/bss/libs/coord" }
+# FIPS-validated SHA-256 for the ledger idempotency payload fingerprint.
+aws-lc-rs = "1.17"
+
 # credstore
 credstore-sdk = { package = "cf-gears-credstore-sdk", version = "0.1.26", path = "gears/credstore/credstore-sdk" }
 

apps/cf-gears-example-server/Cargo.toml

@@ -29,6 +29,7 @@ otel = ["toolkit/otel"]
 account-management = ["dep:account_management"]
 static-idp = ["dep:static-idp-plugin"]
 file-storage = ["dep:file_storage"]
+bss-ledger = ["dep:bss_ledger"]
 
 [dependencies]
 mimalloc = { version = "0.1" }
@@ -78,6 +79,9 @@ mini-chat = { package = "cf-gears-mini-chat", path = "../../gears/mini-chat/mini
 account_management = { package = "cf-gears-account-management", path = "../../gears/system/account-management/account-management", optional = true }
 static-idp-plugin = { package = "cf-gears-static-idp-plugin", path = "../../gears/system/account-management/plugins/static-idp-plugin", optional = true }
 
+# Optional BSS Billing Ledger gear
+bss_ledger = { package = "bss-ledger", path = "../../gears/bss/ledger/ledger", optional = true }
+
 # Optional example module
 users-info = { path = "../../examples/toolkit/users-info/users-info", optional = true }
 calculator-gateway = { path = "../../examples/oop-gears/calculator-gateway/calculator-gateway", optional = true }

apps/cf-gears-example-server/src/registered_gears.rs

@@ -70,3 +70,6 @@ use static_idp_plugin as _;
 
 #[cfg(feature = "account-management")]
 use account_management as _;
+
+#[cfg(feature = "bss-ledger")]
+use bss_ledger as _;

config/e2e-features.txt

@@ -1 +1 @@
-users-info-example,mini-chat,static-tenants,static-authn,static-authz,static-credstore,account-management,static-idp
+users-info-example,mini-chat,static-tenants,static-authn,static-authz,static-credstore,account-management,static-idp,bss-ledger

config/e2e-local.yaml

@@ -265,6 +265,10 @@ gears:
           identity:
             subject_id: "11111111-6a88-4768-9dfc-6bcd5187d9ed"
             subject_tenant_id: "00000000-df51-5b42-9538-d2b56b7ee953"
+            # A real AuthN resolver always sets a subject_type; some gears
+            # (e.g. bss-ledger) require its presence. Additive — gears that do
+            # not check it are unaffected.
+            subject_type: "gts.cf.core.security.subject_user.v1~"
             token_scopes: ["*"]
         # Hierarchy tenant tokens — used by budget allocation e2e tests
         - token: "e2e-token-hierarchy-root"
@@ -364,6 +368,15 @@ gears:
         # rather than silently shipping a half-wired stack.
         required: true
 
+  bss-ledger:
+    # Gear-specific database (SQLite for E2E, like the other user gears; the
+    # gear ships dual PG/SQLite migrations). No config block needed — the
+    # defaults (events_enabled=false, seller_tenant_types=partner+platform)
+    # are correct for E2E.
+    database:
+      server: "sqlite_users"
+      file: "bss_ledger.db"
+
   simple-user-settings:
     # Gear-specific database configuration
     database:

deny.toml

@@ -39,6 +39,9 @@ ignore = [
   "RUSTSEC-2023-0071", # Marvin Attack timing sidechannel in rsa 0.9 — dev-only dep of rustls-corecrypto-provider; used solely for RSA-PSS *verification* (public-key op, no private key involved) in rsa_pss_apple_salt_length_matches_rfc8017 test; no safe upgrade available; advisory itself permits "local use on a non-compromised computer"
   "RUSTSEC-2026-0173", # proc-macro-error2 unmaintained — direct dep of our proc-macro crate cf-gears-toolkit-db-macros (compile-time only, never in any runtime artifact); no advisory of a vulnerability, only maintenance status. Tracked for migration to std syn::Error -> compile_error! emission.
   "RUSTSEC-2026-0187", # lopdf <0.42 unbounded-recursion DoS on crafted PDFs — transitive via kreuzberg→cf-gears-file-parser→cf-gears-example-server (example app only, never parses untrusted PDFs). No usable fix: kreuzberg 4.9.x pins lopdf "^0.41" (<0.42) and the fix landed in 0.42.0; 5.x drops the bundled-pdfium feature we use. Remove once kreuzberg ships a release allowing lopdf >=0.42.
+  "RUSTSEC-2026-0194", # quick-xml <0.41 quadratic-CPU DoS on crafted XML (duplicate-attribute check) — transitive (multiple pinned versions 0.37–0.39 via office/doc parsers under the file-parser example app); we never parse untrusted XML on any request hot path. No unified upgrade yet (each upstream pins its own <0.41). Remove once the transitive pins reach quick-xml >=0.41.
+  "RUSTSEC-2026-0195", # quick-xml <0.41 unbounded namespace-declaration allocation → memory-exhaustion DoS on crafted XML — same transitive quick-xml as RUSTSEC-2026-0194; same rationale (no untrusted-XML hot path, no unified upgrade). Remove together with it once the pins reach >=0.41.
+  "RUSTSEC-2026-0204", # crossbeam invalid-pointer-deref in the `fmt::Pointer` impl for `Atomic`/`Shared` (only when Debug-formatting an already-invalid pointer) — deep transitive dep (tokio/rayon/sccache/… epoch GC), not reachable from our code (we never Debug-print crossbeam atomics). Remove once the transitive crossbeam pins ship the fixed release.
 ]
 
 # Note: