Adapter IR
The language-neutral contract that generates SDKs, MCP tools, docs, and tests.
The adapter IR is the product's source of truth. Clients, docs, MCP tools, and tests are generated from it.
name: destination_portal
version: 0.1.3
label: Destination Portal
origin:
appUrl: https://app.example.test
apiHosts:
- api.example.test
auth:
strategy: captured_headers
requiredHeaders:
- authorization
- x-access-key
tokenExpiry:
header: authorization
type: jwt
operations:
events.list:
backend: http
endpoint: searchEvents
description: Events visible in the destination workspace.
input:
workspaceId: string
transform: transforms/events/list.ts
sideEffects:
category: read
tests:
- fixture: event-list
- live: hasAtLeastOneEvent
verification:
status: verified
verifiedAt: 2026-08-27T10:22:00Z
freshness:
liveProbeMaxAgeDays: 30
demoteTo: raw
declaredExposure:
sdk: true
mcp: true
pipeline: true
records.update:
backend: http
endpoint: updateRecord
description: Update one record using read-modify-write.
sideEffects:
category: update
externalEffects:
- may_notify_users
defaultMode: preview
requiresConfirm: true
knownFacts:
- Updates use POST, not PATCH.
- Send the full editable field set.
- send_notification is forced false.Layers
auth: how sessions are created, refreshed, and probed.endpoints: raw HTTP or GraphQL calls.schemas: request and response shapes.operations: reviewed domain methods.backends: whether an operation uses HTTP, browser automation, or both.verification: whether an operation can be exposed to SDK, MCP, or pipelines.sideEffects: what kind of state change an operation may cause.transforms: raw payloads to stable domain objects.tests: fixture, live, drift, and known-fact assertions.docs: descriptions for humans and agents.
sideEffects.category is the operation risk source of truth. The IR should not
also carry a separate kind: read | write flag that can drift out of sync.
Operation Backends
operations:
users.list:
backend: http
endpoint: userSearch
sideEffects:
category: read
expenses.createDraft:
backend: browser
script: playwright/expenses/createDraft.ts
sideEffects:
category: create
externalEffects:
- submits_external_record
defaultMode: preview
requiresConfirm: true
reports.downloadCsv:
backend: hybrid
setup:
browserScript: playwright/reports/openExport.ts
endpoint: exportCsv
sideEffects:
category: readThe public client method is stable across backend types. Only the adapter implementation changes.
Capabilities And Provenance
Adapters can contain executable pieces: transforms, generated request helpers, and browser-backed scripts. Those pieces need declared capabilities before an adapter can be shared safely.
capabilities:
transforms:
network: none
filesystem: none
environment: none
timers: none
browser:
allowHosts:
- app.example.test
allowDownloads: false
blockNavigationOutsideAllowlist: true
provenance:
source: registry://example-org/[email protected]
captureIds:
- cap_2026_08_27_a91f
llm:
provider: openai
model: gpt-5
signature: ed25519:example-signature
importedAt: 2026-08-27T14:02:00ZA transform should be a pure function over JSON, enforced by the runtime. A browser script should fail if it leaves the declared host allowlist.
Why Not Just OpenAPI
OpenAPI is useful output, but it is not enough for private web apps.
SiteKit adapters need to represent things OpenAPI does not naturally capture:
- Browser-session handoff.
- Browser-backed UI workflows.
- Hybrid browser and HTTP operations.
- Cookie plus CSRF double-submit.
- Server-side active scope, such as selected workspace or account.
- GraphQL operations copied from an app bundle.
- Optional variables that are semantically required.
- Write preview behavior.
- Human-confirmed facts.
- Redacted fixtures and drift tests.
Codegen Targets
The same IR can generate:
- TypeScript client with Zod schemas.
- Python client with Pydantic models.
- MCP server wrapper.
- Markdown docs.
- OpenAPI-like endpoint reference.
- Contract tests.