mcp-scraper 0.25.0 → 0.26.1

package/docs/specs/main-mcp-integration-ownership-spec.md

@@ -0,0 +1,1164 @@
+# Main MCP Integration Ownership
+
+- Status: Implementation in progress — Nango ownership cutover implemented locally; Resend credential migration and production rollout remain
+- Spec date: 2026-07-16
+- Product decision: Integrations belong to the main MCP Scraper system
+- Scheduler decision: Scheduling remains an independent Mastra system and consumes main-MCP integration APIs
+- Primary repos: `mcp-scraper`, `mcp-scraper-scheduler`
+- Incident driver: Search Console displayed `Connected` while direct reads and export returned `connection_transport_unavailable`
+- Supersedes: `connected-services-control-plane-decoupling-spec.md`
+- Preserves: the released connected-account and usage-pricing contract in `unified-credit-and-scheduled-execution-billing-spec.md`
+
+## Implementation receipt — 2026-07-16
+
+Implemented in the working tree:
+
+- main-owned Turso connection, health-event, action-audit, and scheduler-nonce tables;
+- stable public IDs reconciled from server-only Nango routing IDs;
+- direct main-MCP Nango REST and MCP SDK transport for discovery, connect, reconnect, reads, actions, and Search Console export;
+- local connected-usage preflight and idempotent settlement;
+- signed scheduler describe/execute APIs with expiry and replay protection;
+- Mastra proxy tools and deterministic sync execution through main;
+- scheduler logical bindings with no connection foreign key;
+- idempotent scheduler purge endpoint used by disconnect;
+- lifecycle and operational-health separation in the frontend and MCP schemas;
+- `test_service_connection` plus the dashboard Test connection control;
+- canonical `/integrations` aliases while preserving `/schedule-connections` compatibility routes.
+
+Still required before the full specification is complete:
+
+- migrate the Resend remote-MCP credential and OAuth lifecycle from scheduler Postgres into encrypted main-MCP storage;
+- migrate existing scheduler Nango rows and bindings in production while preserving public IDs;
+- deploy both repos with the shared signing secret and `INTEGRATION_OWNER=main`;
+- remove the rollback-only Nango routes, secrets, and legacy tables after the observation window.
+
+## Executive decision
+
+The main MCP Scraper system will own integrations end to end.
+
+This includes:
+
+- the tenant-owned connection record;
+- Nango and remote-MCP credential routing;
+- OAuth connect and reconnect flows;
+- provider catalog and source-controlled tool policy;
+- live schema and capability discovery;
+- direct reads and gated actions;
+- bulk export page execution;
+- operational health and lifecycle state;
+- disconnect and credential deletion;
+- connection audit and deletion receipts;
+- connected-usage authorization and settlement;
+- the public REST, frontend, SDK, and root MCP contracts.
+
+The Mastra scheduler remains a separate system. It owns schedules, due occurrences, leases, agent execution, deterministic sync orchestration, checkpoints, synchronized records, and scheduled-run receipts. When scheduled work needs a connected provider, the scheduler calls the main MCP through signed internal integration APIs. It does not hold Nango secrets, provider credentials, or an authoritative copy of the connection record.
+
+There will be no third integration service.
+
+```text
+Direct use
+  User / Codex / Claude
+    -> Main MCP Scraper
+       -> tenant connection repository
+       -> Nango or remote MCP
+       -> provider
+
+Scheduled use
+  Inngest -> Mastra scheduler
+    -> signed internal call to Main MCP Scraper
+       -> tenant connection repository
+       -> Nango or remote MCP
+       -> provider
+    -> scheduler checkpoint / synchronized records / run receipt
+```
+
+The scheduler is a consumer of integrations, not their owner or transport.
+
+## Product contract in plain language
+
+### Immediate provider use
+
+When a user asks Codex to analyze Search Console, the main MCP directly resolves the user's Search Console connection, checks its state and allowed tools, calls Nango, and returns the provider result. No schedule, Mastra workflow, Inngest occurrence, or scheduler deployment is involved.
+
+### Scheduled provider use
+
+When a scheduled action becomes due, the scheduler claims the occurrence and invokes the same main-MCP integration capability through a signed internal request. Mastra may reason over proxied provider tools, while deterministic sync uses a bounded sync-slice API. The main MCP still owns authorization, provider execution, action gates, and connected-usage billing.
+
+### Connection state
+
+`Connected` means that the OAuth or remote-MCP credential lifecycle is active. It does not promise that Nango or the provider is currently reachable. The product displays credential lifecycle and operational availability separately.
+
+### Recovery
+
+Transport outages produce `Temporarily unavailable`, not `Reconnect required`. Reconnect appears only when authorization evidence proves that the credential expired, was revoked, or lacks a required scope.
+
+## Why the current system is wrong
+
+### Current direct path
+
+The public main API exposes connection routes and root MCP bridge tools, but `src/api/nango-control.ts` defaults its internal target to:
+
+```text
+https://mcp-scraper-scheduler.vercel.app
+```
+
+Connect, reconnect, disconnect, list, describe, read, action, binding, and export-page operations are forwarded into scheduler routes. A normal direct Search Console call therefore depends on a deployment whose product purpose is scheduled work.
+
+### Current state ownership
+
+The scheduler Postgres database currently contains:
+
+- `mem_external_connections`;
+- remote-MCP credential records;
+- action audit;
+- schedule-to-connection bindings;
+- connection sync checkpoints and records;
+- connection sync run receipts.
+
+The first three are integration-owned data. Bindings, checkpoints, synchronized records, and scheduled receipts are scheduler-owned data. They must be separated.
+
+### Current execution ownership
+
+The scheduler repository currently contains Nango and remote-MCP connection clients, live tool discovery, provider policies, direct reads/actions, exports, OAuth sessions, lifecycle changes, and usage metering. Mastra schedules use these directly, but the main MCP also proxies through them.
+
+This makes the scheduler an accidental integration backend.
+
+### Current UI truth gap
+
+The live frontend presented Search Console as `Connected · Ready for sync` because a row existed and approved tools were listed. Actual provider calls returned repeatable HTTP 503 transport failures. The deployed frontend also hid Disconnect for Nango connections despite current local source supporting it.
+
+## Goals
+
+1. Make the main MCP the sole integration authority.
+2. Make direct connected-provider calls independent of scheduler availability.
+3. Keep the scheduler as an autonomous Mastra/Inngest system.
+4. Remove Nango and remote-MCP secrets from the scheduler.
+5. Move connection lifecycle, health, policy, audit, and connected-usage settlement to the main MCP.
+6. Preserve public connection IDs and existing healthy credentials during migration.
+7. Preserve schedules, bindings, checkpoints, synchronized records, and run history.
+8. Separate credential lifecycle from operational health in every public surface.
+9. Keep action safety and connected-usage billing identical for direct and scheduled calls.
+10. Provide a reversible migration with explicit proof and no forced customer reconnection.
+
+## Non-goals
+
+- Merging the scheduler repository into the main MCP repository.
+- Moving Mastra agents, Inngest functions, schedule leases, or sync checkpoints into the main MCP.
+- Replacing Nango as the OAuth/token-refresh provider.
+- Changing connected-account pricing or Credit rates.
+- Replacing deterministic scheduled sync with an LLM.
+- Moving synchronized provider datasets from scheduler Postgres to Turso.
+- Creating a third integration deployment.
+- Renaming every legacy route in the first release.
+- Requiring users to reconnect credentials that can be migrated safely.
+
+## Ownership after migration
+
+| Capability or data | Main MCP | Mastra scheduler | Nango / remote provider |
+|---|---:|---:|---:|
+| Public user/API-key authentication | Yes | No | No |
+| User and billing identity | Yes | No | No |
+| Public connection ID | Yes | Reference only | No |
+| Connection lifecycle record | Yes | No | No |
+| Nango credential/token | Routing metadata only | No | Yes |
+| Remote-MCP encrypted credential | Yes | No | Provider may also hold OAuth grant |
+| Provider read/action policy | Canonical | Generated consumer projection | No |
+| Live tool discovery | Yes | No | Supplies inventory |
+| Direct read/action/export | Yes | No | Executes provider work |
+| Operational health | Yes | Receives response only | Supplies evidence |
+| Connected-usage debit | Yes, authoritative | No | Supplies usage measurement |
+| Schedule definition and occurrence | No | Yes | No |
+| Schedule-to-connection grant | Scheduler stores; main validates signed assertion | Yes | No |
+| Mastra tool proxy | Executes endpoint | Builds proxy tool | No |
+| Deterministic sync checkpoint | No | Yes | No |
+| Synchronized records/table | Pointer only when useful | Yes | No |
+| Scheduled-run base/model billing | Authoritative ledger | Authorizes and reports | Model provider supplies cost |
+
+## Architectural decisions
+
+### D1. Main MCP owns the connection record in Turso
+
+Create main-owned tables in the existing Turso/libSQL database. The authoritative owner is the stable `users.id`, not an email string.
+
+```sql
+CREATE TABLE service_connections (
+  id                          TEXT PRIMARY KEY,
+  user_id                     INTEGER NOT NULL REFERENCES users(id),
+  provider_config_key         TEXT NOT NULL,
+  provider                    TEXT,
+  transport                   TEXT NOT NULL,
+  upstream_connection_id      TEXT,
+  label                       TEXT,
+  lifecycle_status            TEXT NOT NULL,
+  operational_status          TEXT NOT NULL DEFAULT 'unknown',
+  reconnect_required          INTEGER NOT NULL DEFAULT 0,
+  actions_enabled             INTEGER NOT NULL DEFAULT 0,
+  granted_permissions_json    TEXT,
+  enabled_features_json       TEXT,
+  schema_revision             TEXT,
+  provider_contract_version   TEXT NOT NULL,
+  provider_contract_hash      TEXT NOT NULL,
+  last_checked_at             TEXT,
+  last_successful_call_at     TEXT,
+  last_failure_at             TEXT,
+  last_failure_code           TEXT,
+  last_failure_retryable      INTEGER,
+  health_evidence_source      TEXT,
+  consecutive_failures        INTEGER NOT NULL DEFAULT 0,
+  scheduler_table_name        TEXT,
+  scheduler_vault_name        TEXT,
+  legacy_owner_identity       TEXT,
+  created_at                  TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at                  TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(user_id, provider_config_key, upstream_connection_id)
+);
+```
+
+`upstream_connection_id` is server-only and is never returned to browsers or MCP clients. The existing public UUID remains `id`.
+
+### D2. Main MCP owns remote-MCP credentials encrypted at rest
+
+Nango continues to store Nango-backed OAuth credentials. The main MCP stores only Nango routing metadata.
+
+For remote MCPs such as Resend, create an encrypted credential table:
+
+```sql
+CREATE TABLE service_connection_credentials (
+  connection_id              TEXT PRIMARY KEY REFERENCES service_connections(id) ON DELETE CASCADE,
+  credential_kind            TEXT NOT NULL,
+  endpoint                    TEXT NOT NULL,
+  ciphertext                 BLOB NOT NULL,
+  nonce                      BLOB NOT NULL,
+  auth_tag                   BLOB NOT NULL,
+  key_version                TEXT NOT NULL,
+  oauth_client_metadata_json TEXT,
+  created_at                 TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at                 TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+Use envelope encryption with a versioned production secret or KMS-backed data key. Never store plaintext API keys, access tokens, refresh tokens, or OAuth client secrets in Turso. Key rotation must support current and previous key versions.
+
+### D3. Main MCP uses the MCP SDK, not Mastra, for provider transport
+
+The main repository already depends on `@modelcontextprotocol/sdk`. Move or rewrite the connection client using the standard MCP SDK transport. Do not add Mastra to the main MCP merely to call Nango's MCP endpoint or a remote MCP.
+
+The executor interface is provider-neutral:
+
+```ts
+interface IntegrationExecutor {
+  listTools(connection: OwnedServiceConnection): Promise<DiscoveredTool[]>
+  describeTool(connection: OwnedServiceConnection, tool: string): Promise<SanitizedTool>
+  read(connection: OwnedServiceConnection, tool: string, args: JsonObject, context: ExecutionContext): Promise<ExecutionResult>
+  action(connection: OwnedServiceConnection, tool: string, args: JsonObject, context: ActionContext): Promise<ExecutionResult>
+  exportPage(connection: OwnedServiceConnection, request: ExportPageRequest, context: ExecutionContext): Promise<ExportPageResult>
+  disconnect(connection: OwnedServiceConnection, context: MutationContext): Promise<DisconnectResult>
+}
+```
+
+Nango and remote-MCP transports implement the same interface.
+
+### D4. Provider policy is canonical in the main MCP
+
+Move safe read/action classifications, administrative denylists, required permissions/features, sync requirements, health probes, and schema rules into:
+
+```text
+mcp-scraper/src/integrations/contracts/
+```
+
+Generate a scheduler-consumer artifact containing only what scheduled configuration and proxy-tool construction require. The artifact has a version and SHA-256 hash. Scheduler builds fail when their projection is stale.
+
+Callable tools remain an intersection:
+
+```text
+live upstream tools
+  intersect main-owned provider policy
+  intersect active tenant-owned connection
+  intersect verified provider permissions/features
+  intersect account action switch for mutations
+  intersect signed schedule grant for scheduled calls
+```
+
+The scheduler cannot expand this set.
+
+### D5. Scheduler stores only logical connection references and grants
+
+The scheduler continues to own `mem_scheduled_action_connections`, but the table becomes a reference to a main-owned public connection ID, not a foreign key to a scheduler-owned connection row.
+
+Migration shape:
+
+```sql
+ALTER TABLE mem_scheduled_action_connections
+  ADD COLUMN IF NOT EXISTS connection_public_id TEXT,
+  ADD COLUMN IF NOT EXISTS provider_config_key TEXT,
+  ADD COLUMN IF NOT EXISTS connection_label TEXT,
+  ADD COLUMN IF NOT EXISTS provider_contract_hash TEXT;
+```
+
+Backfill `connection_public_id` from the existing `external_connection_id`. After cutover, remove the foreign key to `mem_external_connections` in a controlled table migration. The scheduler validates current ownership and availability through the main MCP before a binding is created or edited.
+
+### D6. Scheduler calls signed internal main-MCP integration endpoints
+
+Add a scoped service-auth contract distinct from browser/API-key authentication and distinct from billing-only secrets.
+
+```text
+INTERNAL_INTEGRATIONS_KEY_CURRENT
+INTERNAL_INTEGRATIONS_KEY_PREVIOUS
+MCP_SCRAPER_INTERNAL_URL
+```
+
+Every request includes:
+
+- scheduler service identity;
+- issued-at and expiry;
+- request ID;
+- method and path;
+- body hash;
+- occurrence ID when scheduled;
+- schedule ID;
+- tenant identity assertion;
+- connection public ID;
+- exact granted tool set or one requested granted tool;
+- provider-contract hash;
+- HMAC signature.
+
+The main MCP verifies the signature, expiry, replay nonce, tenant mapping, connection ownership, provider contract, requested tool, action switch, and billing authorization.
+
+### D7. Mastra receives proxy tools, never Nango credentials
+
+Replace `scheduled-action-nango-tools.ts` direct Nango clients with main-MCP proxy tools. Mastra still sees provider-shaped tools with bounded schemas, but execution performs a signed call to the main MCP.
+
+```text
+Mastra tool.execute(args)
+  -> internal main MCP /integrations/:id/read or /action
+  -> main-owned executor
+  -> Nango/remote MCP
+  -> normalized result and usage receipt
+```
+
+The scheduler may cache sanitized tool schemas by `connectionId + schemaRevision + providerContractHash`. It never caches credentials or upstream connection IDs.
+
+### D8. Deterministic sync uses a bounded sync-slice endpoint
+
+Scheduled `connection_sync` remains deterministic and scheduler-owned. It calls:
+
+```text
+POST /api/internal/integrations/:id/sync-slice
+```
+
+Input includes dataset, bounded time range, page size, cursor, schedule ID, and occurrence ID. Main validates and executes provider work. Scheduler persists normalized records, checkpoints, typed tables, and the run receipt.
+
+Main returns usage receipts so connected function/Proxy/compute costs settle once in the authoritative main ledger. The scheduler charges the scheduled occurrence base separately under its existing contract.
+
+### D9. Direct connected usage settles locally in main
+
+After migration, a direct integration call no longer makes a scheduler-to-main billing callback. Main authorizes and settles connected usage against its own Credit ledger in the same product boundary.
+
+For scheduled integration calls, the signed request carries an occurrence-scoped idempotency identity. Main settles connected usage; scheduler settles only the scheduled base and model cost. Duplicate occurrence retries cannot duplicate connected usage debits.
+
+### D10. Lifecycle and operational health are separate
+
+```ts
+type ConnectionLifecycleStatus =
+  | 'pending_oauth'
+  | 'connected'
+  | 'reauth_required'
+  | 'deleting'
+  | 'cleanup_pending'
+  | 'disconnected'
+
+type ConnectionOperationalStatus =
+  | 'unknown'
+  | 'available'
+  | 'temporarily_unavailable'
+  | 'rate_limited'
+  | 'permission_limited'
+  | 'provider_error'
+```
+
+Only confirmed authentication evidence changes lifecycle to `reauth_required`. Transport 5xx, timeout, Nango discovery failure, billing unavailability, and provider rate limiting update operational health without invalidating the credential.
+
+### D11. Health comes from actual operations and explicit tests
+
+The Integrations page does not probe every provider on load.
+
+Health evidence comes from:
+
+- connect/reconnect verification;
+- explicit `test_service_connection`;
+- direct read/action/describe/export;
+- scheduled proxy calls and sync slices.
+
+Evidence expires to `unknown` after a provider-contract TTL. The UI always displays the last-check timestamp and safe error code when present.
+
+For Search Console, the safe diagnostic is `list-sites` with empty arguments. Success proves the main MCP reached Nango, Google accepted the credential, and Search Console returned a valid site collection. It does not prove a named property exists or has performance rows.
+
+### D12. Disconnect is a distributed deletion saga
+
+Main owns the deletion request and durable receipt:
+
+1. verify user ownership and idempotency key;
+2. mark lifecycle `deleting`;
+3. revoke/delete the upstream Nango or remote-MCP credential;
+4. call the scheduler's idempotent purge endpoint for bindings, checkpoints, sync data, and pending work tied to the public connection ID;
+5. delete main encrypted credentials and connection metadata;
+6. reconcile the recurring Nango quantity in Stripe;
+7. finalize the deletion receipt.
+
+If step 3 fails, retain the active local record in `deleting` and retry safely. If step 4 fails after upstream revocation, set `cleanup_pending`; the connection is unusable and billing quantity is removed only when the defined commercial deletion point is satisfied. The cleanup worker retries without recreating credentials.
+
+Ordinary users never receive a force-local-delete path. Administrative override is separately authorized and audited.
+
+### D13. Reconnect preserves the logical connection
+
+Reconnect updates the same main-owned public connection ID. It preserves schedule bindings, table/vault pointers, audit history, billing identity, and health history. If Nango rotates the upstream routing ID, only the server-only field changes.
+
+Reconnect cannot create a second billable row for the same logical tenant/provider account.
+
+### D14. Main deployment identity governs integration release parity
+
+Expose a release projection containing:
+
+```json
+{
+  "service": "mcp-scraper-main",
+  "releaseId": "...",
+  "integrationSchemaVersion": "...",
+  "providerContractVersion": "...",
+  "providerContractHash": "...",
+  "frontendReleaseId": "..."
+}
+```
+
+The scheduler exposes its consumed provider-contract hash. Production smoke fails when hashes differ or when the deployed frontend lacks Test, Refresh/Reconnect, and Disconnect controls promised by main.
+
+## Main MCP data model
+
+### `service_connections`
+
+Authoritative public connection identity, tenant ownership, routing metadata, lifecycle, operational health, capability revision, and scheduler pointers.
+
+### `service_connection_credentials`
+
+Encrypted remote-MCP credentials only. Nango credentials remain in Nango.
+
+### `service_connection_tool_cache`
+
+Bounded sanitized live tool schemas keyed by connection, tool, upstream revision, and provider-contract hash. Cache entries never grant authorization by themselves.
+
+```sql
+CREATE TABLE service_connection_tool_cache (
+  connection_id          TEXT NOT NULL REFERENCES service_connections(id) ON DELETE CASCADE,
+  tool_name              TEXT NOT NULL,
+  classification         TEXT NOT NULL,
+  schema_json            TEXT NOT NULL,
+  schema_hash            TEXT NOT NULL,
+  upstream_revision      TEXT,
+  provider_contract_hash TEXT NOT NULL,
+  fetched_at             TEXT NOT NULL,
+  expires_at             TEXT NOT NULL,
+  PRIMARY KEY(connection_id, tool_name)
+);
+```
+
+### `service_connection_health_events`
+
+Stores safe operational evidence without arguments or provider results.
+
+### `service_connection_action_audit`
+
+Stores tenant, connection, tool, redacted argument classification, status, safe error, idempotency identity, and timestamp. It contains no provider credential or unbounded payload.
+
+### `service_connection_deletions`
+
+Durable saga receipt covering upstream revocation, scheduler cleanup, local cleanup, and billing reconciliation.
+
+### `service_connection_migrations`
+
+Records scheduler-to-main backfill receipts, hashes, verification, and cutover state per connection.
+
+## Identity migration
+
+The scheduler currently keys connection ownership by email-like identity strings. Main ownership must use stable `users.id`.
+
+Migration rules:
+
+1. Read the scheduler connection row and its legacy identity.
+2. Resolve exactly one active main user by normalized email or existing memory identity.
+3. Preserve the existing public connection UUID.
+4. Store the old identity only in `legacy_owner_identity` for audit/migration lookup.
+5. Never infer ownership when zero or multiple users match; quarantine that row for operator review.
+6. Verify Nango routing metadata without exposing it.
+7. Write a migration receipt containing safe hashes, not secrets.
+
+No connection becomes public under a different user merely because labels or provider accounts match.
+
+## Scheduler data model after migration
+
+The scheduler retains:
+
+- `mem_scheduled_actions`;
+- `mem_scheduled_action_connections` with logical public IDs and grants;
+- `mem_connection_sync_checkpoints`;
+- `mem_connection_sync_records`;
+- typed provider tables such as Search Console performance;
+- `mem_connection_sync_runs`;
+- schedule and model billing receipts.
+
+The scheduler removes or retires:
+
+- authoritative `mem_external_connections` rows;
+- Nango routing identifiers;
+- remote-MCP credential rows;
+- direct provider action audit;
+- Nango usage authorization/settlement ownership;
+- public connect/reconnect/disconnect/list/read/action/export routes.
+
+`mem_external_connections` remains a read-only migration shadow for one rollback window, then is dropped after evidence confirms no remaining readers.
+
+## Public API contract
+
+Use integration-named routes:
+
+```text
+GET    /integrations
+POST   /integrations/connect-session
+POST   /integrations/:id/reconnect-session
+POST   /integrations/:id/test
+DELETE /integrations/:id
+POST   /integrations/:id/actions-enabled
+POST   /integrations/:id/read
+POST   /integrations/:id/describe
+POST   /integrations/:id/action
+POST   /integrations/:id/export
+```
+
+Keep `/schedule-connections/*` as compatibility aliases for at least one published MCP/package window. Alias handlers call the same main-owned services; they never forward to the scheduler after cutover.
+
+### Public connection shape
+
+```ts
+interface PublicServiceConnection {
+  connectionId: string
+  providerConfigKey: string
+  provider: string | null
+  label: string
+  transport: 'nango' | 'remote_mcp'
+  lifecycleStatus: ConnectionLifecycleStatus
+  operationalStatus: ConnectionOperationalStatus
+  reconnectRequired: boolean
+  actionsEnabled: boolean
+  readTools: string[]
+  actionTools: string[]
+  toolCapabilities: ToolCapability[]
+  lastCheckedAt: string | null
+  lastSuccessfulCallAt: string | null
+  lastFailureAt: string | null
+  lastFailureCode: string | null
+  lastFailureRetryable: boolean | null
+  healthEvidenceSource: string | null
+  schemaRevision: string | null
+  providerContractVersion: string
+  tableName: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+```
+
+Compatibility field `status` remains temporarily and maps only to lifecycle. Documentation must not treat it as runtime health.
+
+## Internal scheduler-to-main API
+
+These routes require signed scheduler service authentication and are not exposed through the root MCP:
+
+```text
+GET  /api/internal/integrations/contracts
+GET  /api/internal/integrations/:id/toolset
+POST /api/internal/integrations/:id/read
+POST /api/internal/integrations/:id/action
+POST /api/internal/integrations/:id/sync-slice
+POST /api/internal/integrations/:id/validate-binding
+POST /api/internal/integrations/:id/report-scheduler-pointer
+```
+
+### Scheduled invocation shape
+
+```ts
+interface ScheduledIntegrationInvocation {
+  requestId: string
+  scheduleId: string
+  occurrenceId: string
+  tenantIdentity: string
+  connectionId: string
+  providerConfigKey: string
+  tool: string
+  allowedTools: string[]
+  providerContractHash: string
+  args: JsonObject
+  issuedAt: string
+  expiresAt: string
+  nonce: string
+}
+```
+
+Main verifies every field and ignores any upstream routing value supplied by scheduler.
+
+## Error contract
+
+| Code | HTTP | Lifecycle effect | Operational effect | Correct recovery |
+|---|---:|---|---|---|
+| `connection_not_found` | 404 | none | none | Select another connection |
+| `connection_inactive` | 409 | depends on confirmed cause | unknown | Inspect lifecycle evidence |
+| `provider_auth_revoked` | 401/409 | reauth required | permission limited | Reconnect |
+| `missing_provider_permission` | 403 | connected | permission limited | Refresh access with required scope |
+| `integration_transport_unavailable` | 503 | connected | temporarily unavailable | Retry/test; operator checks main/Nango |
+| `tool_discovery_failed` | 502 | connected | provider error | Retry and inspect Nango inventory |
+| `upstream_rate_limited` | 429 | connected | rate limited | Honor Retry-After |
+| `provider_error` | 502 | connected | provider error | Retry or inspect provider status |
+| `integration_not_configured` | 503 | connected | temporarily unavailable | Fix main deployment configuration |
+| `billing_authorization_unavailable` | 503 | connected | temporarily unavailable | Retry; do not reconnect |
+| `schedule_grant_invalid` | 403 | unchanged | unchanged | Scheduler refreshes binding/grant |
+| `provider_contract_mismatch` | 409 | unchanged | unknown | Deploy matching contract versions |
+| `actions_disabled` | 403 | connected | unchanged | Explicitly enable actions |
+| `action_outcome_unknown` | 409 | connected | unchanged | Verify provider before another action |
+
+Every error includes `requestId`, `retryable`, `sourceLayer`, and a safe message.
+
+After cutover, external clients should receive `integration_transport_unavailable`. Accept and map legacy `connection_transport_unavailable` during the compatibility window.
+
+## Frontend behavior
+
+### Badges
+
+| Lifecycle | Operational | Badge | Action |
+|---|---|---|---|
+| connected | available | Available | Test again |
+| connected | unknown | Connected · Not tested | Test connection |
+| connected | temporarily unavailable | Temporarily unavailable | Retry test |
+| connected | rate limited | Rate limited | Retry later |
+| connected | permission limited | Limited access | Refresh access |
+| reauth required | any | Reconnect required | Reconnect |
+| pending OAuth | unknown | Authorization pending | Continue authorization |
+| deleting | any | Disconnecting | Show progress/retry state |
+| cleanup pending | any | Disconnected · Cleanup pending | Contact support with receipt ID |
+
+`Ready for sync` additionally requires recent operational availability and every required sync tool.
+
+### Drawer controls
+
+Every connection transport shows:
+
+- Test connection;
+- Refresh access or Reconnect based on lifecycle;
+- Disconnect;
+- action switch when actions exist;
+- last successful operation;
+- last safe failure and request ID;
+- connection public reference;
+- provider-contract and schema revision under operator details.
+
+Disconnect is never conditioned on `remote_mcp` transport.
+
+### Search Console outage message
+
+For integration transport failure:
+
+> Your Google authorization remains connected, but the main MCP could not reach the integration transport. Retrying OAuth is unlikely to help. Retry Test connection or contact support with request ID …
+
+## Root MCP contract
+
+Keep existing generic tools:
+
+- `list_service_connections`;
+- `describe_service_connection_tool`;
+- `read_service_connection`;
+- `call_service_connection_action`;
+- `export_connected_service_data`.
+
+Add:
+
+- `test_service_connection`.
+
+All execute inside the main MCP integration layer. None call the scheduler unless the user explicitly creates, edits, inspects, or runs scheduled work.
+
+Tool descriptions distinguish lifecycle from operational health. A stored row with `reconnectRequired: false` is not described as healthy without current evidence.
+
+## Search Console workflow contract
+
+A comprehensive analysis begins:
+
+1. list main-owned service connections;
+2. select the tenant Search Console connection;
+3. inspect lifecycle and operational evidence;
+4. test the connection when health is unknown or stale;
+5. call `list-sites` directly through main;
+6. match the exact requested property by normalized site URL/domain;
+7. declare and query/export a bounded date range;
+8. validate row count, coverage, and provider warnings;
+9. enrich relevant pages and queries with scraper, SERP, PAA, Maps, or competitor data;
+10. distinguish Search Console facts from public-web inference.
+
+Failure before valid provider rows blocks the Search Console analysis. Public data may be presented separately but cannot masquerade as a Search Console result.
+
+## Source movement map
+
+### Move or rewrite into `mcp-scraper`
+
+| Scheduler source | Main destination/responsibility |
+|---|---|
+| `routes/nango-integrations.ts` | `src/api/integration-routes.ts` plus main service layer |
+| `routes/resend-integrations.ts` | main remote-MCP lifecycle routes |
+| `db/external-connections.ts` connection portion | Turso connection repository |
+| `db/remote-mcp-connections.ts` credential portion | encrypted main credential repository |
+| `lib/nango-api.ts` | main Nango API client and canonical policy input |
+| `lib/nango-connection-client.ts` | MCP SDK-based main transport |
+| `lib/nango-connected-mcp-catalog.ts` | main schema discovery/cache |
+| `lib/nango-proxy.ts` | main Nango Proxy adapter |
+| `lib/connected-data-export.ts` provider page adapters | main export execution |
+| `lib/connected-usage-billing.ts` | local main ledger authorization/settlement adapter |
+| connection action audit | main Turso action audit |
+
+### Keep and refactor in scheduler
+
+| Scheduler source | Required change |
+|---|---|
+| `agents/scheduled-action-nango-tools.ts` | replace Nango handles with signed main-MCP proxy tools |
+| `lib/connection-sync.ts` | call main sync-slice API; keep checkpoints/storage |
+| `db/external-connections.ts` binding/sync portion | split into scheduler-owned binding and sync repositories |
+| connection table/vault helpers | remain scheduler-owned storage pointers |
+| scheduled action workflows/steps | remain Mastra/Inngest |
+| schedule billing | retain scheduled base/model settlement; remove connected-usage ownership |
+
+## Secrets and configuration
+
+### Add to main MCP deployment
+
+```text
+NANGO_SECRET_KEY
+NANGO_MCP_URL
+NANGO_API_BASE_URL
+INTEGRATION_CREDENTIAL_KEY_CURRENT
+INTEGRATION_CREDENTIAL_KEY_PREVIOUS
+INTERNAL_INTEGRATIONS_KEY_CURRENT
+INTERNAL_INTEGRATIONS_KEY_PREVIOUS
+```
+
+### Remove from scheduler after cutover
+
+```text
+NANGO_SECRET_KEY
+NANGO_MCP_URL
+NANGO_API_BASE_URL
+SCHEDULE_INTEGRATIONS_SECRET
+remote-MCP credential encryption secrets
+```
+
+The scheduler keeps only the scoped key used to sign requests to main.
+
+Secret migration uses deployment secret-copy procedures and masked verification. Secrets never appear in logs, migration receipts, specs, or chat.
+
+## Reliability
+
+### Read retry policy
+
+Main may retry read-only discovery, reads, and export pages for retryable transport failures:
+
+- original attempt plus at most two retries;
+- exponential backoff with jitter;
+- total within the public deadline;
+- honor Retry-After;
+- never retry validation, permission, or confirmed auth failures.
+
+### Action policy
+
+Actions require an idempotency key. Ambiguous provider outcomes return `action_outcome_unknown` and are not automatically replayed.
+
+### Main integration circuit breaker
+
+Open a short provider/transport circuit after deployment-wide retryable failures cross a threshold. Fail fast without marking individual credentials for reconnect. Scheduled occurrences receive a retryable infrastructure result and retain their occurrence identity.
+
+### Scheduler behavior during main outage
+
+If the main MCP is unavailable before provider execution:
+
+- preserve the occurrence and checkpoint;
+- do not double-charge scheduled base or connected usage;
+- retry under the same occurrence identity;
+- report an infrastructure failure, not an OAuth failure;
+- do not attempt direct Nango fallback from scheduler.
+
+There is intentionally no scheduler bypass around main ownership.
+
+## Security
+
+1. Main public authentication derives `user_id`; callers cannot submit another tenant identity.
+2. Internal scheduler calls use signed, short-lived, replay-protected assertions.
+3. Main re-resolves every connection from `connectionId + user_id`.
+4. Scheduler never supplies or receives Nango upstream routing IDs.
+5. Foreign and absent connection IDs return the same public not-found shape.
+6. Remote-MCP credentials are encrypted with versioned keys.
+7. Logs never contain credentials, tool arguments, provider payloads, Search Console rows, or prompts.
+8. Action authorization remains independent of billing.
+9. Schedule grants cannot exceed the main provider policy or account action switch.
+10. Migration scripts emit only safe hashes and counts.
+
+## Observability
+
+Propagate one request ID through:
+
+```text
+public MCP/frontend or scheduler occurrence
+  -> main route
+  -> integration executor
+  -> Nango/remote MCP/provider
+  -> usage ledger
+  -> health event
+```
+
+Record:
+
+- source surface: direct, scheduled-agent, scheduled-sync, UI-test;
+- provider and operation class;
+- duration and retries;
+- safe result/error code;
+- lifecycle and operational transitions;
+- schema and provider-contract revisions;
+- usage authorization/settlement receipt IDs;
+- schedule/occurrence IDs for internal calls;
+- migration and deletion saga states.
+
+Alert when:
+
+- integration failure rate affects multiple tenants;
+- Nango discovery fails above threshold;
+- scheduler provider-contract hash differs from main;
+- migration receipts remain incomplete;
+- scheduler still uses legacy Nango routes after cutover;
+- deletion or cleanup sagas stall;
+- recurring connection quantity differs from active main-owned Nango rows;
+- frontend and main release contracts differ.
+
+## Migration plan
+
+### Phase 0 — repair current production and stop misleading users
+
+1. Diagnose and restore the current scheduler-hosted transport so existing customers are not left broken during migration.
+2. Deploy the current transport-neutral Disconnect frontend.
+3. Change optimistic `Ready for sync` wording to lifecycle-only `Connected` until health fields ship.
+4. Add request IDs to current proxy errors.
+5. Prove Search Console `list-sites` and bounded export using the existing connection.
+
+Exit gate:
+
+- current direct Search Console calls work;
+- live Nango Disconnect is visible;
+- no customer credential is recreated merely to fix infrastructure.
+
+### Phase 1 — build main-owned integration foundation
+
+1. Add Turso schema and repositories.
+2. Add canonical provider contracts in main.
+3. Add MCP SDK Nango and remote-MCP executors.
+4. Add local connected-usage authorization and settlement.
+5. Add health, audit, tool cache, migration, and deletion repositories.
+6. Add new `/integrations` services behind a disabled feature flag.
+
+Feature flags:
+
+```text
+INTEGRATION_OWNER=legacy_scheduler|shadow_main|main
+INTEGRATION_MAIN_EXECUTION_ENABLED=false|true
+```
+
+Exit gate:
+
+- unit and contract tests pass;
+- main can execute against staging connections without scheduler code;
+- no production traffic is cut over.
+
+### Phase 2 — migrate connection metadata and credentials
+
+1. Create a one-time migration exporter in scheduler.
+2. Resolve each legacy identity to exactly one main user.
+3. Preserve every public connection UUID.
+4. Backfill Nango routing metadata into main.
+5. Re-encrypt remote-MCP credentials into main using the new key.
+6. Verify provider, transport, status, labels, action switch, pointers, and safe hashes.
+7. Dual-write lifecycle changes from the legacy path during the migration window.
+8. Quarantine unmatched or ambiguous owners; do not guess.
+
+Exit gate:
+
+- every eligible connection has a verified migration receipt;
+- Nango and remote-MCP staging calls pass through main;
+- no duplicate billable connection is created;
+- remote-MCP plaintext is never exported.
+
+### Phase 3 — shadow direct reads and cut over main
+
+Shadow only safe read-only operations:
+
+- catalog/list comparison;
+- live tool inventory comparison;
+- bounded diagnostic comparison against disposable fixtures.
+
+Do not shadow actions, OAuth sessions, reconnect, disconnect, or billed bulk export.
+
+Then set `INTEGRATION_OWNER=main` for direct traffic. `/schedule-connections` aliases remain but execute locally in main.
+
+Exit gate:
+
+- scheduler deployment can be disabled in staging while direct list/test/read/describe/export works;
+- direct usage settles once in main;
+- health states and request traces are correct.
+
+### Phase 4 — convert scheduler into a main-MCP consumer
+
+1. Add signed internal integration client.
+2. Replace Mastra Nango tools with proxy tools.
+3. Replace deterministic sync provider calls with sync-slice requests.
+4. Backfill logical connection references in binding tables.
+5. Remove scheduler foreign-key dependence on `mem_external_connections`.
+6. Verify schedule grants against main on create/edit and execution.
+7. Retain checkpoints, records, tables, and occurrence receipts in scheduler.
+
+Exit gate:
+
+- scheduled agent and deterministic sync run without Nango secrets in scheduler;
+- same provider-contract hash is used;
+- schedule retries do not double bill;
+- existing bindings still target the preserved public IDs.
+
+### Phase 5 — delete legacy ownership from scheduler
+
+1. Remove public integration control routes from scheduler.
+2. Remove Nango and remote-MCP secrets from scheduler deployment.
+3. Stop dual writes.
+4. Freeze `mem_external_connections` as read-only for one rollback window.
+5. Prove zero legacy readers through telemetry.
+6. Delete migrated remote-MCP credential ciphertext from scheduler.
+7. Drop legacy connection tables only after backup retention and migration sign-off.
+8. Remove `NANGO_CONTROL_URL` and `SCHEDULE_INTEGRATIONS_SECRET` from main.
+
+Exit gate:
+
+- scheduler is independently deployable as a Mastra scheduling system;
+- direct integrations are entirely main-owned;
+- no legacy route traffic or secret remains.
+
+## Repository task breakdown
+
+### `mcp-scraper`
+
+- MI-01: Add main integration schema and migration registry entries.
+- MI-02: Add stable user-owned connection repository.
+- MI-03: Add encrypted remote-MCP credential repository and key rotation.
+- MI-04: Move canonical provider contracts into main and generate scheduler projection.
+- MI-05: Implement MCP SDK Nango client and live tool discovery.
+- MI-06: Implement remote-MCP client and OAuth/API-key lifecycle.
+- MI-07: Implement main read/action/describe/export executor.
+- MI-08: Integrate connected usage with the local Credit ledger.
+- MI-09: Implement lifecycle and operational health state.
+- MI-10: Implement action audit, health events, and request traces.
+- MI-11: Implement Test connection and Search Console safe probe.
+- MI-12: Implement idempotent disconnect saga and cleanup retries.
+- MI-13: Implement reconnect identity preservation and duplicate prevention.
+- MI-14: Add signed scheduler invocation verification and replay protection.
+- MI-15: Add `/integrations` routes and compatibility aliases.
+- MI-16: Update root MCP schemas, instructions, and `test_service_connection`.
+- MI-17: Update frontend states and universal lifecycle controls.
+- MI-18: Add release/provider-contract parity metadata.
+- MI-19: Add migration import and verification tooling.
+- MI-20: Update docs, MCPB, generated manifest, SDK types, and legal surfaces.
+
+### `mcp-scraper-scheduler`
+
+- MS-01: Split scheduler-owned bindings/sync state from legacy connection repository.
+- MS-02: Add migration exporter with safe hashes and no plaintext output.
+- MS-03: Add signed main-MCP integration client.
+- MS-04: Replace direct Nango Mastra tools with proxy tools.
+- MS-05: Replace deterministic provider execution with sync-slice calls.
+- MS-06: Migrate bindings to logical public IDs and remove connection foreign key.
+- MS-07: Validate provider-contract hash and exact grants.
+- MS-08: Add idempotent connection purge endpoint for disconnect saga.
+- MS-09: Remove connected-usage settlement ownership.
+- MS-10: Remove public integration routes, credentials, and legacy tables after proof.
+
+## Testing
+
+### Main unit tests
+
+- user ownership and foreign-ID nondisclosure;
+- connection lifecycle/operational transitions;
+- provider contract generation/hash;
+- MCP SDK schema sanitization;
+- Nango and remote-MCP transport selection;
+- encrypted credential round-trip and key rotation;
+- read retry eligibility and deadline budget;
+- action idempotency and ambiguous outcomes;
+- health TTL expiry;
+- Search Console list-sites probe;
+- local connected-usage debit idempotency;
+- signed scheduler request verification, expiry, and replay rejection;
+- disconnect saga states and retry;
+- reconnect preserves public ID and quantity.
+
+### Scheduler unit tests
+
+- proxy tool schema and main endpoint execution;
+- exact grant enforcement before dispatch;
+- provider-contract hash mismatch fails closed;
+- occurrence identity survives retries;
+- sync-slice checkpoint persistence;
+- purge endpoint removes binding/sync state idempotently;
+- no code path opens a Nango client after cutover.
+
+### Cross-repo contract tests
+
+- scheduler projection matches main provider-contract hash;
+- signed invocation schemas match;
+- normalized result and error schemas match;
+- old and new public route aliases are equivalent;
+- main release contract matches frontend bundle;
+- root MCP tool manifest contains health fields and Test connection;
+- scheduler package/deployment contains no Nango secret requirement in main-owner mode.
+
+### Migration tests
+
+- exact email-to-user match;
+- missing user quarantine;
+- ambiguous user quarantine;
+- public UUID preservation;
+- Nango routing metadata backfill;
+- remote credential re-encryption without plaintext logs;
+- action switch and table/vault pointer preservation;
+- dual-write conflict detection;
+- rollback reads legacy shadow without overwriting main.
+
+### End-to-end staging tests
+
+1. Disable scheduler and prove direct Search Console list/test/read/export through main.
+2. Disable main integration execution and prove scheduler fails safely without Nango fallback.
+3. Run a scheduled Mastra agent with proxied provider tools.
+4. Run deterministic Search Console sync through sync-slice.
+5. Revoke a Google grant and verify only main marks reauth required.
+6. Reconnect and verify the same public connection and bindings.
+7. Disconnect a disposable fixture and verify upstream, main, scheduler, and billing cleanup exactly once.
+8. Rotate internal signing and remote credential keys.
+9. Verify request trace and usage receipt continuity.
+
+### Production proof
+
+For the existing Search Console tenant, record sanitized evidence only:
+
+- main and scheduler release IDs;
+- matching provider-contract hashes;
+- main-owned public connection ID;
+- lifecycle and operational states;
+- successful `list-sites` count and exact matched property URL;
+- bounded export count/date range/warnings;
+- UI screenshot with Test, Refresh/Reconnect, and Disconnect;
+- direct request trace containing no scheduler hop;
+- scheduled request trace showing scheduler-to-main hop;
+- one connected-usage receipt per provider operation;
+- unchanged recurring connection quantity during migration.
+
+## Acceptance criteria
+
+The change is complete only when:
+
+1. Main Turso is authoritative for every connection record.
+2. Main owns Nango and remote-MCP execution.
+3. Main owns encrypted remote-MCP credential storage.
+4. Scheduler contains no Nango or provider credential.
+5. Scheduler downtime does not affect direct integrations.
+6. Direct integration requests contain no scheduler network hop.
+7. Scheduler uses signed main-MCP proxy tools for scheduled provider work.
+8. Mastra and Inngest remain scheduler-owned.
+9. Scheduler checkpoints, synchronized records, and run receipts remain intact.
+10. Existing public connection IDs and schedule bindings are preserved.
+11. No healthy customer connection is forced to reauthorize during migration.
+12. Lifecycle and operational health are distinct everywhere.
+13. A transport 503 never becomes Reconnect required.
+14. Search Console Test connection runs directly through main.
+15. Geny's Flowers property selection uses an exact accessible property URL.
+16. Refresh/Reconnect and Disconnect are visible for Nango connections.
+17. Disconnect revokes upstream access and cleans main, scheduler, and billing state exactly once.
+18. Reconnect preserves logical identity and billable quantity.
+19. Main is the sole provider-policy source.
+20. Scheduler fails closed on a provider-contract hash mismatch.
+21. Main is the sole connected-usage debit authority and executor.
+22. Scheduled base/model billing remains correctly separated.
+23. Production frontend and backend releases are in parity.
+24. Legacy scheduler integration routes show zero traffic before removal.
+25. All unit, contract, migration, staging, and production proof gates pass.
+
+## Rollback
+
+Rollback is phase-specific:
+
+### Before direct cutover
+
+Disable main execution and retain legacy scheduler proxying. Keep additive main tables and migration receipts.
+
+### After direct cutover but before scheduler conversion
+
+Set `INTEGRATION_OWNER=legacy_scheduler` for read-only direct operations. Do not fail over OAuth sessions, reconnect, actions, or disconnect automatically because duplicate side effects are possible.
+
+### After scheduler conversion
+
+Scheduler may temporarily use the read-only legacy shadow only if the legacy Nango secrets have not yet been removed and an explicit rollback is approved. It must never dynamically bypass main during an outage.
+
+### After secret removal
+
+Rollback means redeploying a verified previous release with intentionally restored secrets, not silently reactivating stale scheduler code. Completed reconnects and disconnects are never replayed.
+
+Health truth, request IDs, and the corrected frontend must not be rolled back even when execution ownership is temporarily reverted.
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Turso becomes authoritative for more integration state | Additive migrations, explicit repository tests, stable user IDs, migration receipts |
+| Remote credentials move databases | Envelope encryption, key rotation, no plaintext exporter, verified deletion from scheduler |
+| Scheduler loses direct provider access | Signed proxy tools, bounded deadlines, retryable occurrence semantics, no hidden fallback |
+| Cross-system grant spoofing | HMAC request signing, replay protection, main ownership check, exact grant and contract hash validation |
+| Scheduled latency increases | Same-region calls, connection reuse, schema caching, sync-slice batching |
+| Duplicate billing during cutover | One owner flag, occurrence-scoped idempotency, shadowing excludes billed calls |
+| Public IDs change | Preserve scheduler UUIDs as main primary keys |
+| Binding FK removal weakens local integrity | Main validation on create/edit/execute plus scheduler cleanup saga |
+| Source policy drifts | Main canonical contract and generated scheduler projection |
+| Main outage affects schedules | Correct dependency: scheduler retries; it does not take over integration ownership |
+| Frontend remains stale | Release identity and live bundle contract smoke |
+
+## Evidence anchors
+
+### Main MCP
+
+- `src/api/db.ts`: Turso/libSQL user, billing, workflow, and migration authority.
+- `src/api/nango-control.ts`: current main-to-scheduler connection proxy and legacy error mapping.
+- `src/api/server.ts`: public connection, lifecycle, read/action/export, binding, and billing routes.
+- `src/api/connected-data-export.ts`: aggregate export orchestration already in main.
+- `src/api/connected-account-billing.ts`: recurring connection quantity contract.
+- `src/api/connected-usage-billing.ts`: authoritative main connected-usage boundary.
+- `src/mcp/http-mcp-tool-executor.ts`: root MCP bridge.
+- `src/mcp/mcp-tool-schemas.ts`: public generic integration schemas.
+- `public/app.jsx` and `public/app.js`: main integration frontend and current local transport-neutral Disconnect.
+
+### Scheduler
+
+- `src/mastra/routes/nango-integrations.ts`: accidental Nango integration API owner.
+- `src/mastra/routes/resend-integrations.ts`: accidental remote-MCP lifecycle owner.
+- `src/mastra/db/external-connections.ts`: mixed integration and scheduling persistence.
+- `src/mastra/db/remote-mcp-connections.ts`: scheduler-held remote credentials.
+- `src/mastra/lib/nango-api.ts`: provider catalog, policy, Nango API, and routing.
+- `src/mastra/lib/nango-connection-client.ts`: Mastra MCP connection client to replace in main with standard MCP SDK.
+- `src/mastra/agents/scheduled-action-nango-tools.ts`: direct provider tools to convert into main-MCP proxies.
+- `src/mastra/lib/connection-sync.ts`: deterministic sync orchestration that remains scheduler-owned.
+- `src/mastra/lib/connected-usage-billing.ts`: scheduler-to-main billing client to retire for provider execution.
+
+## Final architectural statement
+
+Integrations are part of MCP Scraper's main product surface and security boundary.
+
+The main MCP owns the connection, credential route, provider policy, provider call, health truth, lifecycle mutation, audit, export, and connected-usage charge. The Mastra scheduler owns when scheduled work runs, how it is orchestrated, and where scheduled state is stored. It invokes integrations through main like any other authorized internal consumer; it never becomes the integration backend again.