Files
ai/object/commerce_native.go
zeekay a089000671 feat(billing): plan rolling-window AI-spend cap gate (Anthropic-style)
Adds a THIRD, orthogonal gate to the balance filter: a plan's rolling-window
AI-spend cap (resets continuously — usage older than the window falls out of the
trailing sum). Distinct from insufficient_balance: a caller WITH money is denied
429 usage_cap_exceeded when their plan's trailing-window budget is momentarily
spent, bounding burst spend per @hanzo/plans ai.rolling_cap_usd / _window_hours.

- object/commerce_native.go: RollingCapReaderFunc + Set/RollingCapReader() hook,
  mirroring the TierReader native-billing seam. The HOST (hanzoai/cloud) implements
  it against the in-proc finance ledger + plan lookup; nil (standalone ai) = no-op.
- routers/filter_balance.go: consult it in the sufficient-balance branch; deny 429
  only on a positively-computed over-cap. FAILS OPEN on any reader error — a finance
  blip must never 429 a paying caller (subscription-shaped limit, like the tier gate,
  not the funding gate). Hard money bounds stay the balance gate + monthly spend_percent.
- test: over-cap→429, under-cap→admit, reader-error→fail-open, unwired→no-op.

Inert until the host wires SetRollingCapReader (cloud build.go wireFinance) — no
behavior change for standalone ai or the current cloud pin.
2026-07-20 13:05:34 -07:00

113 lines
6.1 KiB
Go

// Copyright 2023-2025 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package object
import "context"
// The ONE native billing seam. A HOST binary that embeds this module co-resident
// with the finance ledger (hanzoai/cloud, unified binary) installs these typed hooks
// at boot; every prepaid balance read + usage debit then dispatches DIRECTLY to the
// host's in-process finance client (per-org SQLite double-entry wallet) — no HTTP, no
// socket, no serialization: in-proc ZAP, not a network hop. nil (the default, e.g.
// standalone ai) → the call falls back to the module's HTTP path against
// commerceEndpoint, unchanged. This replaces the prior http.RoundTripper transport
// seam: money is a TYPED call now, never an HTTP request the host has to re-route.
// BalanceReaderFunc returns the subject's AVAILABLE prepaid balance in CENTS within
// the org namespace. subject is the billing subject ("owner/name" for a per-user
// wallet or the org slug for a pooled wallet); namespace is the org (X-Org-Id).
type BalanceReaderFunc func(ctx context.Context, subject, namespace, currency string) (availableCents int64, err error)
// UsageRecorderFunc debits a metered usage event from the subject's wallet.
type UsageRecorderFunc func(ctx context.Context, u UsageEvent) error
// UsageEvent is one metered debit — the typed twin of the old /v1/billing/usage body.
type UsageEvent struct {
Subject string // billing subject (SourceId): "owner/name" or org slug
Namespace string // org (X-Org-Id)
// USD is the EXACT amount to debit as a decimal USD string ("0.00132"), never a
// rounded cent. The host parses it to atto-USD (1e-18) so a sub-cent AI call bills
// precisely and is never floored to zero. Empty or "0" debits nothing.
USD string
Currency string // default "usd"
Model string
Provider string
RequestID string // idempotency key
}
// TierReaderFunc returns the subject's commerce subscription-plan NAME
// (free | starter | pro | enterprise) within the org namespace — the co-resident
// twin of the family per-tier gate's HTTP lookup. subject is the billing subject
// ("owner/name" or the org slug); namespace is the org (X-Org-Id). A HOST binary
// (hanzoai/cloud) installs it so the tier is read through the in-process commerce
// transport with the service token commerce accepts — NOT an authed self-call to
// the cloud edge, which the edge would 401/403 (the toothless-gate bug: the gate
// then saw "" and failed open). nil (the default, e.g. standalone ai) → the tier
// lookup falls back to the module's HTTP path, unchanged. A "" name with a nil error
// means the tier is UNKNOWN, which the gate treats as ALLOW (fail-safe), so a
// commerce blip never locks a paying caller out of a SKU they already had.
type TierReaderFunc func(ctx context.Context, subject, namespace string) (name string, err error)
// RollingCapReaderFunc reports whether the subject has EXCEEDED its plan's rolling
// AI-spend cap within the trailing window — the Anthropic-style burst limit that
// resets continuously (usage older than the window falls out of the sum, so there is
// no fixed reset boundary). The HOST (hanzoai/cloud) implements it: resolve the
// subject's plan tier → its ai.rolling_cap_usd + ai.rolling_window_hours (canonical
// @hanzo/plans entitlements) → sum the subject's AI spend over the trailing window
// from the in-process finance ledger → return over = (windowSpend >= cap). A plan
// with no cap configured returns over=false.
//
// This is a THIRD gate, orthogonal to the two the family SKU gates answer (does the
// PLAN include this model / may we spend our CASH on a prepaid upstream): it bounds
// how fast a caller may burn their OWN budget, per plan. It is a subscription-shaped
// limit, so it FAILS SAFE like the tier gate, not like the funding gate: on ANY
// uncertainty the host returns (false, err) and the caller here treats a non-nil err
// as ALLOW — a finance/commerce blip must never 429 a paying caller whose plan and
// balance already admit the call. The hard money bounds remain the per-request
// balance gate (below) and the monthly ai.spend_percent ceiling (commerce). nil (the
// default, standalone ai) → no rolling cap, behavior unchanged.
type RollingCapReaderFunc func(ctx context.Context, subject, namespace string) (over bool, err error)
var (
balanceReader BalanceReaderFunc
usageRecorder UsageRecorderFunc
tierReader TierReaderFunc
rollingCapReader RollingCapReaderFunc
)
// SetBalanceReader installs the host's native balance reader (nil clears it).
func SetBalanceReader(f BalanceReaderFunc) { balanceReader = f }
// SetUsageRecorder installs the host's native usage recorder (nil clears it).
func SetUsageRecorder(f UsageRecorderFunc) { usageRecorder = f }
// SetTierReader installs the host's native subscription-tier reader (nil clears it).
func SetTierReader(f TierReaderFunc) { tierReader = f }
// SetRollingCapReader installs the host's native rolling-window cap reader (nil clears it).
func SetRollingCapReader(f RollingCapReaderFunc) { rollingCapReader = f }
// BalanceReader returns the installed native reader, or nil when unset (standalone).
func BalanceReader() BalanceReaderFunc { return balanceReader }
// UsageRecorder returns the installed native recorder, or nil when unset.
func UsageRecorder() UsageRecorderFunc { return usageRecorder }
// TierReader returns the installed native tier reader, or nil when unset (standalone).
func TierReader() TierReaderFunc { return tierReader }
// RollingCapReader returns the installed native rolling-cap reader, or nil when unset.
func RollingCapReader() RollingCapReaderFunc { return rollingCapReader }