Runtime Guarantees

SiteKit adapters should not each reinvent basic operational discipline. The runtime provides guarantees that every generated client and MCP server inherits.

Politeness

runtime:
  rateLimit:
    maxParallel: 2
    minDelayMs: 500
  retry:
    attempts: 3
    backoffMs: [1000, 4000, 15000]
  failureBudget:
    maxConsecutiveFailures: 5
    cooldownMinutes: 30

Failure paths should wait longer, not skip throttles. A lapsed session or provider-side refusal is exactly when the client should slow down.

Adapters can override runtime defaults per operation when the site behaves differently by route:

operations:
  reports.downloadCsv:
    runtime:
      rateLimit:
        maxParallel: 1
        minDelayMs: 2000

  users.search:
    runtime:
      rateLimit:
        maxParallel: 3
        minDelayMs: 300

The default should be polite. Overrides should be reviewed evidence, not a way to push a provider harder.

Negative Caching

Some valid requests return empty results. Empty should not always mean "try again immediately."

runtime:
  negativeCache:
    enabled: true
    retryAfterDays: 30
    keys:
      - operation
      - input.recordId
      - input.kind

Negative caching is especially useful for bulk data pulls where a provider may publish records late but most empty responses will stay empty.

Validation

Generated clients validate inputs and responses at the adapter boundary.

SchemaValidationError
  adapter: [email protected]
  operation: records.getMetrics
  path: metrics[0].value
  expected: number
  received: string

Validation failures are drift signals. They should be visible in logs, pipelines, and repair workflows.

Telemetry

Runtime telemetry should capture:

• Operation name and adapter version.
• Backend type: http, browser, or hybrid.
• Auth refresh attempts.
• Retry and backoff events.
• Schema validation failures.
• Negative cache hits.
• Provider status codes.

This telemetry belongs to the adapter runtime. Business metrics belong to downstream apps.

Budgeted Live Probes

Live probes cost provider calls. At scale, SiteKit should prioritize them by:

• Adapter usage.
• Operation criticality.
• Recent drift signals.
• Auth failure rate.
• Time since last successful live test.

Fixture tests are cheap and should run often. Live tests should be scheduled with provider respect and operational value in mind.

Live probe freshness feeds exposure. If an operation's live evidence expires or drift signals accumulate, generated surfaces should demote it before unattended jobs depend on stale assumptions.