Connectivity

Connectivity is how SpineWorkspace connects to external systems. External applications are execution providers. They are not workspaces.

Connector Contract

Every connector defines:

interface ConnectorContract {
  id: ConnectorId;
  name: string;
  category: ConnectorCategory;
  auth: {
    type: "oauth2" | "apikey" | "mcp" | "direct";
    scopes: string[];
    refreshPolicy: string;
  };
  capabilities: {
    provided: CapabilityId[];
    read: EntityType[];
    write: EntityType[];
    sync: SyncMode;
  };
  health: {
    checkInterval: number;
    timeout: number;
    retryPolicy: RetryPolicy;
    circuitBreaker: boolean;
  };
  mapping: {
    entities: EntityMapping[];
    fields: FieldMapping[];
    transforms: Transform[];
  };
}

Communication Hierarchy

Execution follows a strict communication hierarchy:

Priority	Method	Scope
1	In-process function call	Same Worker
2	Repository access	D1/KV/R2/DO
3	Service binding	Same-account Worker
4	Queue	Async propagation
5	External HTTP	Browser/SaaS boundary only

Rule: Worker-to-Worker HTTP on the same account is an anti-pattern.

Sync Rules

• Sync runs after Spine commit
• Sync failures do not invalidate successful execution
• Sync status is surfaced explicitly in UI
• Retry uses exponential backoff with circuit breaker

Fallback Rules

• UI fails open with realistic data when connectors are unavailable
• UI never surfaces raw provider errors as product state
• Marketplace catalog remains loadable without external dependencies

Invariants

1. The UI never depends on external application UIs
2. The UI never imports provider SDKs directly
3. Authoritative field mapping lives in the connector contract, not in views
4. Connector health is observable, retryable, and auditable

Connector Lifecycle

DISCOVER → VALIDATE → INSTALL → AUTHORIZE → REGISTER → GOVERN → EXECUTE

Phase	Description
Discover	Find connector in marketplace
Validate	Verify compatibility and requirements
Install	Add connector to tenant
Authorize	Grant OAuth/API access
Register	Register capabilities in registry
Govern	Apply policies to connector usage
Execute	Use connector for operations

Three Marketplaces

Marketplace	Purpose
Integration Marketplace	External system connectors
Plugin Marketplace	Workbench extensions
MCP Marketplace	AI tool capabilities

Rules:

• Marketplace is capability discovery/distribution
• Marketplace is not canonical truth
• Plugin installed ≠ permission
• MCP available ≠ authority

Communication Bridge

The Communication Bridge preserves:

• Tenant identity
• Work context
• Purpose and provenance
• Correlation and authority

The Bridge is NOT:

• Canonical memory
• Authority
• A replacement database
• An unrestricted agent bus

Related

• Capability Fabric — what connectors enable
• Execution Fabric — how connectors are used
• Spine Schema — what connectors produce
• Reconciliation — how connector results are verified