Unclassified

Unified Registry Schema

Status: SUPERSEDED REGISTRY SNAPSHOT. This file is a source for registry
concepts but is not the canonical schema or credential/auth contract. Use
../architecture/IMPLEMENTATION_CONTRACT_v1.1.md
and the typed registry packages/code.

Original status: CANONICAL
Scope: Single source of truth for all platform registries — credentials, connectors, MCP, ADK, capabilities.
Last Updated: 2026-07-25

Registry Architecture

All registries share a common envelope:

registry:
  id: string          # unique identifier
  version: string     # semver
  updated_at: string  # ISO 8601
  tenant_id: string   # null for platform-wide registries
  metadata:
    owner: string     # team or service responsible
    environment: "development" | "staging" | "production"

1. Credential Registry

Purpose

Track every secret, key, and credential across the platform. Answers: what exists, where it lives, who uses it, when it rotates.

Schema

credentials:
  <credential_id>:
    # Identity
    name: string                    # human-readable name
    type: "api_key" | "secret" | "token" | "connection_string" | "certificate" | "webhook_secret"

    # Classification
    category: "platform" | "tenant" | "connector" | "service" | "webhook" | "infrastructure"
    sensitivity: "public" | "internal" | "confidential" | "secret"

    # Storage
    storage:
      provider: "doppler" | "cloudflare_secrets" | "vercel_env" | "d1" | "encrypted_kv"
      path: string                  # location within provider
      encrypted: boolean

    # Distribution
    consumers:                      # which services receive this
      - service: string             # e.g., "gateway", "loader", "knowledge"
        environment: string
        required: boolean

    # Lifecycle
    created_at: string
    expires_at: string | null
    rotation:
      policy: "manual" | "90d" | "30d" | "on_demand"
      last_rotated: string | null
      next_rotation: string | null

    # Audit
    last_used_at: string | null
    usage_count: number
    compromised: boolean
    compromised_at: string | null

Example

credentials:
  descope_management_key:
    name: "Descope Management Key"
    type: "api_key"
    category: "platform"
    sensitivity: "secret"
    storage:
      provider: "doppler"
      path: "/integratewise/prd_web-unified/DESCOPE_MANAGEMENT_KEY"
      encrypted: true
    consumers:
      - service: "gateway"
        environment: "production"
        required: true
      - service: "mcp-connector"
        environment: "production"
        required: false
    rotation:
      policy: "90d"
      last_rotated: "2026-06-15T00:00:00Z"
      next_rotation: "2026-09-13T00:00:00Z"
    compromised: false

2. Connector Registry

Purpose

Catalog all integrations available to tenants. Answers: what connectors exist, what they do, how they authenticate, what data they sync.

Schema

connectors:
  <connector_id>:
    # Identity
    name: string
    slug: string                    # URL-safe identifier
    description: string
    category: "crm" | "project_management" | "communication" | "finance" | "analytics" | "storage" | "custom"

    # Provider
    provider:
      name: string                  # e.g., "salesforce", "jira", "slack"
      website: string
      logo_url: string

    # Authentication
    auth:
      type: "oauth2" | "api_key" | "basic" | "bearer" | "webhook"
      oauth_config:
        authorize_url: string
        token_url: string
        scopes: string[]
        redirect_uri_template: string
      credential_ref: string       # points to credential registry

    # Data Model
    sync:
      direction: "inbound" | "outbound" | "bidirectional"
      entities:                     # what objects are synced
        - name: string
          fields: string[]
          primary_key: string
          sync_frequency: "realtime" | "hourly" | "daily" | "manual"
      webhooks:
        - event: string
          endpoint: string
          secret_ref: string        # points to credential registry

    # Status
    status: "available" | "beta" | "deprecated" | "disabled"
    installed_by_count: number
    last_sync_at: string | null

    # Publishing
    published:
      marketplace: boolean
      visibility: "public" | "private" | "unlisted"
      approved_at: string | null
      approved_by: string | null

Example

connectors:
  salesforce:
    name: "Salesforce CRM"
    slug: "salesforce"
    description: "Bidirectional sync with Salesforce CRM"
    category: "crm"
    provider:
      name: "Salesforce"
      website: "https://salesforce.com"
      logo_url: "/icons/salesforce.svg"
    auth:
      type: "oauth2"
      oauth_config:
        authorize_url: "https://login.salesforce.com/services/oauth2/authorize"
        token_url: "https://login.salesforce.com/services/oauth2/token"
        scopes: ["api", "refresh_token"]
        redirect_uri_template: "https://gateway.integratewise.ai/api/v1/connectors/{slug}/callback"
      credential_ref: "salesforce_oauth_client"
    sync:
      direction: "bidirectional"
      entities:
        - name: "Account"
          fields: ["Id", "Name", "Industry", "ARR__c", "Health_Score__c"]
          primary_key: "Id"
          sync_frequency: "hourly"
        - name: "Contact"
          fields: ["Id", "FirstName", "LastName", "Email", "AccountId"]
          primary_key: "Id"
          sync_frequency: "hourly"
      webhooks:
        - event: "account.updated"
          endpoint: "/api/v1/webhooks/salesforce"
          secret_ref: "salesforce_webhook_secret"
    status: "available"
    installed_by_count: 23
    published:
      marketplace: true
      visibility: "public"

3. MCP Registry

Purpose

Catalog all MCP tools and resources available to agents. Answers: what tools exist, what they do, what they require, how they're invoked.

Schema

mcp_registry:
  tools:
    <tool_id>:
      # Identity
      name: string
      description: string
      category: "spine" | "connector" | "memory" | "governance" | "analytics" | "custom"

      # Interface
      input_schema: object          # JSON Schema for inputs
      output_schema: object         # JSON Schema for outputs

      # Requirements
      requires:
        auth: boolean
        tenant_scoped: boolean
        permissions: string[]       # required roles
        capabilities: string[]      # required capability registry entries

      # Runtime
      implementation:
        worker: string              # which CF worker serves this
        timeout_ms: number
        retry_policy: "none" | "exponential" | "fixed"

      # Health
      status: "available" | "degraded" | "unavailable"
      last_health_check: string | null
      avg_latency_ms: number
      error_rate: number

      # Versioning
      version: string
      deprecated: boolean
      replaced_by: string | null

  resources:
    <resource_id>:
      name: string
      description: string
      type: "read" | "write" | "subscribe"
      schema: object
      required_tools: string[]

Example

mcp_registry:
  tools:
    spine_query:
      name: "Query Spine Entity"
      description: "Query entities from the Spine store by type, filters, and pagination"
      category: "spine"
      input_schema:
        type: "object"
        properties:
          entity_type: { type: "string" }
          filters: { type: "object" }
          limit: { type: "integer", default: 50 }
        required: ["entity_type"]
      output_schema:
        type: "object"
        properties:
          entities: { type: "array" }
          total: { type: "integer" }
          has_more: { type: "boolean" }
      requires:
        auth: true
        tenant_scoped: true
        permissions: ["read:entities"]
      implementation:
        worker: "integratewise-spine"
        timeout_ms: 5000
        retry_policy: "exponential"
      status: "available"
      version: "1.0.0"

4. ADK Registry

Purpose

Catalog agent definitions and their capabilities. Answers: what agents exist, what they can do, how they're triggered, what resources they use.

Schema

adk_registry:
  agents:
    <agent_id>:
      # Identity
      name: string
      description: string
      type: "twin" | "specialist" | "orchestrator" | "swarm"

      # Capabilities
      capabilities: string[]        # references to capability registry
      mcp_tools: string[]           # references to MCP registry

      # Triggers
      triggers:
        - type: "event" | "schedule" | "manual" | "handoff"
          config: object

      # Resources
      memory:
        scope: "tenant" | "session" | "ephemeral"
        max_tokens: number
      knowledge:
        sources: string[]           # knowledge base references

      # Governance
      requires_approval: boolean
      approval_role: string | null
      max_actions_per_hour: number

      # Runtime
      model: string                 # AI model used
      temperature: number
      max_tokens: number

      # Status
      status: "active" | "disabled" | "testing"
      version: string

Example

adk_registry:
  agents:
    csm_twin:
      name: "CSM Twin"
      description: "Customer Success Manager AI agent with full account context"
      type: "twin"
      capabilities:
        - monitor_health
        - generate_qbr
        - propose_actions
        - send_outreach
      mcp_tools:
        - spine_query
        - memory_search
        - signal_generate
      triggers:
        - type: "event"
          config:
            event: "account.health_changed"
            threshold: 0.3
        - type: "schedule"
          config:
            cron: "0 9 * * 1" # Every Monday at 9am
      memory:
        scope: "tenant"
        max_tokens: 8192
      governance:
        requires_approval: true
        approval_role: "cs_manager"
        max_actions_per_hour: 10
      model: "claude-sonnet-4-20250514"
      temperature: 0.3
      status: "active"
      version: "1.0.0"

5. Capability Registry

Purpose

Define executable capability contracts. Answers: what a capability does, what it needs, what it produces, who can invoke it.

Schema

capability_registry:
  capabilities:
    <capability_id>:
      # Identity
      name: string
      description: string
      domain: "revenue" | "csm" | "finance" | "people" | "operations" | "marketing"

      # Workflow
      steps:
        - id: string
          name: string
          handler: "ai" | "human" | "system" | "hybrid"
          requires_approval: boolean
          timeout_ms: number

      # Data Requirements
      requires_data:
        - entity_type: string
          fields: string[]
          must_exist: boolean
      requires_signals:
        - signal_type: string
          threshold: number
          time_window_days: number

      # Permissions
      permissions:
        - role: string
          can_invoke: boolean
          can_approve: boolean
          data_access: "own" | "team" | "org"

      # Output
      produces:
        type: string
        fields: Record<string, string>
        destinations: string[]

      # Governance
      requires_audit: boolean
      requires_approval: boolean
      approval_role: string | null

      # Metrics
      success_rate_target: number
      human_approval_rate_target: number
      typical_duration_ms: number

      # Versioning
      version: string
      status: "active" | "deprecated" | "testing"
      deprecation_notice: string | null

Example

capability_registry:
  capabilities:
    monitor_account_health:
      name: "Monitor Account Health"
      description: "Continuously monitor account health signals and generate alerts"
      domain: "csm"
      steps:
        - id: "collect_signals"
          name: "Collect Health Signals"
          handler: "system"
          requires_approval: false
          timeout_ms: 30000
        - id: "analyze_health"
          name: "AI Health Analysis"
          handler: "ai"
          requires_approval: false
          timeout_ms: 60000
        - id: "generate_alert"
          name: "Generate Health Alert"
          handler: "system"
          requires_approval: false
          timeout_ms: 5000
      requires_data:
        - entity_type: "Account"
          fields: ["health_score", "last_touch", "renewal_date", "arr"]
          must_exist: true
      requires_signals:
        - signal_type: "engagement_drop"
          threshold: 0.3
          time_window_days: 30
      permissions:
        - role: "csm"
          can_invoke: true
          can_approve: false
          data_access: "team"
        - role: "cs_manager"
          can_invoke: true
          can_approve: true
          data_access: "org"
      produces:
        type: "alert"
        fields:
          severity: "string"
          message: "string"
          recommended_action: "string"
        destinations: ["timeline", "email", "slack"]
      requires_audit: true
      requires_approval: false
      success_rate_target: 0.95
      human_approval_rate_target: 0.0
      typical_duration_ms: 45000
      version: "1.0.0"
      status: "active"

Cross-Registry Relationships

Credential Registry ←── Connector Registry
       ↑                      ↓
  MCP Registry ────→ Capability Registry
       ↑                      ↓
  ADK Registry ←──── Agent Runtime

Relationship Rules

  1. Credential → Connector: Every connector auth references exactly one credential entry
  2. Connector → MCP: Each connector exposes tools via MCP; tool IDs are namespaced: {connector}:{tool}
  3. MCP → Capability: Capabilities compose MCP tools into workflows
  4. ADK → Capability: Agents declare which capabilities they can invoke
  5. ADK → MCP: Agents declare which MCP tools they use directly
  6. All → Credential: Every registry entry that needs auth references the credential registry

Migration Path

  1. Phase 1: Populate credential registry from infrastructure/secrets/registry.yaml + Doppler
  2. Phase 2: Populate connector registry from infrastructure/config/connectors/catalog.yaml
  3. Phase 3: Populate MCP registry from infrastructure/config/mcp/tools-registry.yaml
  4. Phase 4: Populate ADK registry from services/iw-agent-runtime config
  5. Phase 5: Populate capability registry from packages/core/capability-registry/types.ts definitions
  6. Phase 6: Wire registry APIs: /api/v1/registries/{type} for discovery