Wahoo provides provider-neutral contracts for operations code. It does not ship a queue, cloud adapter, SMTP client, payment provider, or billing system.

> **Work in progress:** Do not use Wahoo in production yet.

## Jobs

Use `jobs.Runner` with an application queue adapter. It pulls work only when a worker is free, keeps no in-memory backlog, and sets a 5-minute per-job deadline by default.

```go
runner, err := jobs.New(source, handler, jobs.Config{
    Workers:    4,
    JobTimeout: 2 * time.Minute,
})
if err != nil {
    return err
}
return runner.Run(ctx)
```

The queue adapter must define acknowledgement, retry delay, maximum attempts, dead-letter behavior, retention, and transactional outbox handling. Run workers as a workload separate from public HTTP.

## Storage

`storage.Store` defines bounded object operations. The application authorizes opaque object keys and chooses S3, GCS, R2, local storage, or another adapter. Do not expose provider keys or provider ACLs to browsers.

## Mail

`mail.Message` validates recipients and body bounds before an application `mail.Sender` sends it. Queue and retry mail from an application job handler. Do not add unbounded attachments to the mail path.

## Audit Events

`audit.Event` stores a bounded, immutable business event. Include the actor, target, outcome, and Wahoo request ID. The application owns retention, redaction, storage transactions, and audit-log access rules.

## Webhooks

Use `webhook.Verifier` to verify raw payload HMAC-SHA256 signatures with a bounded body and freshness window.

```go
body, err := verifier.ReadBody(r.Body)
if err != nil {
    return err
}
_, err = verifier.Verify(r.Header.Get("Webhook-Signature"), body)
```

Verification proves authenticity and bounded freshness. The application must atomically record provider delivery IDs and process events idempotently to prevent replay.

## Entitlements And Billing

`entitlement.Decide` evaluates normalized feature grants. `billing.Provider` defines checkout and normalized subscription access. `billing.UsageRecorder` records an idempotent metered event.

```go
checkout, err := provider.CreateCheckout(ctx, billing.CheckoutRequest{
    CustomerID: "cus_123",
    PriceID:    "price_team",
    SuccessURL: "https://app.example.com/billing/success",
    CancelURL:  "https://app.example.com/billing/cancel",
})
```

The application owns provider credentials, checkout authorization, webhook reconciliation, invoices, tax, payment recovery, usage aggregation, and conversion from subscription state to entitlement grants.