Performance characteristics

This document is the dense reference companion to the public guide Middleware performance and latency. It maps the HTTP hops Kit middleware triggers per guarded tool call, documents Gateway rate limits and timeouts, and states what observability exists today.

Paybond does not publish Kit p50/p99 benchmarks. Treat all duration guidance as qualitative unless you measure in your own environment.

Design principles

1. Serial hops per guarded call. The interceptor authorizes, executes the handler, completes the spend decision, then submits evidence — in order. There is no batch verify API for multiple tools in one HTTP request.
2. Gateway composes policy; Harbor authorizes capability. POST /verify always reaches Harbor for capability validation when Harbor is configured. Gateway may add Postgres idempotency and spend-policy evaluation around that forward.
3. Evidence path differs by bind mode. Sandbox binds use Gateway guardrails evidence composition. Production attach binds sign payee evidence locally and call /harbor/intents/{id}/evidence through recognition + fraud gates.
4. Kit runs off-platform. Production latency observation defaults to Gateway/Harbor SLIs and partner APM — not Paybond-hosted Kit telemetry.

Hop model (production attach)

sequenceDiagram
  autonumber
  actor Kit as Kit interceptor
  participant GW as Gateway
  participant PG as Postgres
  participant HB as Harbor

  Kit->>GW: POST /verify (Bearer API key)
  GW->>PG: Idempotency + spend policy
  GW->>HB: POST /verify (mTLS, 30s timeout)
  HB-->>GW: allow / deny + audit
  GW-->>Kit: decision_id, audit_id

  Note over Kit: Local tool handler (durationMs in trace only)

  Kit->>GW: POST /v1/spend/decisions/{id}/complete
  opt stripe_mpp session metering
    GW->>HB: POST /internal/v1/mpp/voucher/finalize
  end
  GW-->>Kit: consumed / released

  Kit->>Kit: Sign payee evidence + recognition proof
  Kit->>GW: POST /harbor/intents/{id}/evidence
  GW->>GW: Recognition verify + fraud hardening
  GW->>HB: POST /intents/{id}/evidence (mTLS)
  HB-->>GW: predicate_passed, evaluation
  GW-->>Kit: 200 JSON

Hop summary table

Settlement confirm (POST /harbor/intents/{id}/settlement/confirm) is outside the default auto-evidence interceptor path unless your app calls it explicitly after evidence.

Sandbox and offline paths

Offline mode does not predict production latency.

Authorization cache

Split authorize / execute frameworks can avoid a second /verify when:

Implementation: kit/ts/src/agent/authorization-cache.ts (Python parity in paybond_kit.agent).

Gateway timeouts and retries

Harbor client timeout

Gateway Harbor HTTP clients use a 30 second request timeout, including:

• CallHarborVerify (go/gateway/internal/spendauth/harbor.go)
• Harbor mutation proxies (go/gateway/internal/httpserver/harbor.go)
• Sandbox guardrail Harbor forwards (sandbox_guardrails.go)

Kit SDK retry loop

Default maxRetries: 3 on Paybond / HarborClient gateway HTTP (kit/ts/src/index.ts).

Tail latency on upstream blips can reach several seconds across retries — not represented in dev trace events.

Rate limits (default Gateway windows)

Per-tenant unless noted. Source: go/gateway/internal/httpserver/router.go.

Exceeding limits returns 429 with Retry-After — interacts with SDK retry backoff.

Spend-policy evaluation may contend on Postgres rows during high /verify concurrency; scope policies narrowly for hot operations.

Trace event limits

PaybondTraceEvent (kit/ts/src/agent/types.ts) exposes phase timestamps and handler timing only.

Dev trace (paybond dev trace, .paybond/dev-trace.jsonl) and hosted /demo/agent-trace replay use the same vocabulary. They are phase debuggers, not network profilers.

There are no authorize_duration_ms or evidence_duration_ms fields in the shipped trace schema today.

Production observability map

Kit does not phone home per-tool latency unless you wire traceSink or Gateway agent-run reporting.

Qualitative sizing guidance

Order-of-magnitude on healthy same-region hosted infra: ~20–150ms per Paybond HTTP hop, plus handler time and retry tails on errors.

Related documentation

• Public guide: Middleware performance and latency
• Integration: Agent middleware
• Trace phases: Middleware trace
• Evidence signing cost path: Evidence & artifacts
• Support matrix (what Kit does not ship): Support matrix