Verification and Exposure

Discovery creates candidates. Verification creates product surface.

SiteKit should allow generated or hand-authored operations to exist before they are safe for SDK users, MCP tools, or unattended jobs. Unverified operations are useful during repair and exploration, but they should not be exposed by default.

Operation Status

operations:
  records.update:
    backend: http
    endpoint: updateRecord
    sideEffects:
      category: update
      defaultMode: preview
      requiresConfirm: true
    verification:
      status: verified
      lastReviewedAt: 2026-08-27
      verifiedAt: 2026-08-27T10:22:00Z
      evidence:
        - fixture: update-record-preview
        - liveTest: update-record-no-notify
      freshness:
        liveProbeMaxAgeDays: 30
        demoteTo: raw
    declaredExposure:
      sdk: true
      mcp: true
      pipeline: true
      raw: true

operations:
  records.create:
    backend: http
    endpoint: createRecord
    sideEffects:
      category: create
      defaultMode: preview
      requiresConfirm: true
    verification:
      status: unverified
      reason: Captured during onboarding but not tested against a safe record.
    declaredExposure:
      sdk: false
      mcp: false
      pipeline: false
      raw: true

Exposure Surfaces

• raw: available to adapter authors and repair workflows.
• sdk: generated TypeScript and Python client methods.
• mcp: generated tools available to agents.
• pipeline: approved for unattended jobs.

An operation can be callable in raw mode while still hidden from SDK and MCP surfaces.

Effective Exposure

Declared exposure is an adapter author's intent. Effective exposure is what the runtime actually allows.

effectiveExposure = declaredExposure AND fresh AND trusted

An operation drops to a safer surface automatically when its trust inputs decay:

• Last live probe is older than the operation's freshness policy.
• Drift signals exceed the operation's failure budget.
• Required signature or provenance cannot be verified.
• Auth probe no longer proves the expected account or workspace scope.

The adapter file does not need to be rewritten for this to happen. sitekit status should show what demoted and what would restore exposure:

destination_portal.events.list
  declared: sdk, mcp, pipeline, raw
  effective: raw
  reason: live probe expired 12 days ago
  restore: run sitekit test destination_portal --live --operation events.list

Side Effects

Write safety should describe the kind of side effect, not just whether something is a write.

sideEffects:
  category: update
  externalEffects:
    - may_notify_users
  defaultMode: preview
  requiresConfirm: true
  safeguards:
    - force send_notification=false
    - read current record before write

Useful categories:

• read
• idempotent_write
• create
• update
• delete
• bulk_change
• notifies_third_parties
• spends_money
• submits_external_record

This lets MCP tools and clients communicate risk without embedding business approval logic inside SiteKit.

Verification Evidence

Verification should point to durable evidence:

• Redacted fixture.
• Live probe result.
• Human review answer.
• Known-fact assertion.
• Browser trace or screenshot for browser-backed operations.
• LLM prompt bundle when a model proposed the operation.

The goal is not to remove human judgment. The goal is to make every exposed operation explain why it is trusted.