Unified Platform Embedding Registry Contract

Summary

Different AI services in the platform can still define embedding compatibility in separate places. This creates coordination risk and can lead to incompatible model configurations being deployed without a single source of truth.

Details

Current state mixes multiple sources of embedding contract truth:

• Gateway alias declarations in alias capabilities
• Knowledge-scoped profile model in Portal DB
• Service-level config fields in Knowledge runtime

Evidence from schema and docs:

-- Alias-level embedding contract shape
required_capabilities->'embeddingSpace'

-- Knowledge-scoped embedding profile model
CREATE TABLE IF NOT EXISTS knowledge_embedding_profile_t (
    expected_space_id VARCHAR(255) NOT NULL,
    expected_space_revision BIGINT NOT NULL,
    dimension INTEGER NOT NULL,
    normalization VARCHAR(16) NOT NULL,
    distance_metric VARCHAR(24) NOT NULL,
    document_input_transform_version VARCHAR(255) NOT NULL,
    query_input_transform_version VARCHAR(255) NOT NULL
)

// Knowledge service config fields
pub embedding_space_id: String,
pub embedding_space_revision: u64,
pub embedding_dimension: usize,

The gap is no single platform-wide contract/API that all consumers must use.

Recomendations

• Define one canonical embedding registry contract used by all services.
• Standardize publication-time validation against that contract.
• Define ownership and lifecycle policy (versioning, deprecation, migration).

Start by comparing the embedding contract sources named in the issue: alias capabilities, the Portal DB knowledge_embedding_profile_t schema, and Knowledge runtime configuration. Define completion as a single documented registry contract with publication-time validation and explicit ownership, versioning, deprecation, and migration policies across the consumers.