diff --git a/gears/system/types-registry/docs/PRD.md b/gears/system/types-registry/docs/PRD.md index 205745f8d..1f9942a3b 100644 --- a/gears/system/types-registry/docs/PRD.md +++ b/gears/system/types-registry/docs/PRD.md @@ -1,117 +1,584 @@ -# PRD +# PRD - Types Registry + + + +- [1. Overview](#1-overview) + - [1.1 Purpose](#11-purpose) + - [1.2 Background / Problem Statement](#12-background--problem-statement) + - [1.3 Goals (Business Outcomes)](#13-goals-business-outcomes) + - [1.4 Glossary](#14-glossary) +- [2. Actors](#2-actors) + - [2.1 Human Actors](#21-human-actors) + - [2.2 System Actors](#22-system-actors) +- [3. Operational Concept & Environment](#3-operational-concept--environment) +- [4. Scope](#4-scope) + - [4.1 In Scope](#41-in-scope) + - [4.2 Out of Scope](#42-out-of-scope) +- [5. Functional Requirements](#5-functional-requirements) + - [5.1 Registry Core](#51-registry-core) + - [5.2 Platform Extension Registry](#52-platform-extension-registry) + - [5.3 References, Aliases, And Queries](#53-references-aliases-and-queries) + - [5.4 Ownership, Lifecycle, And Caching](#54-ownership-lifecycle-and-caching) +- [6. Non-Functional Requirements](#6-non-functional-requirements) + - [6.1 Gear-Specific NFRs](#61-gear-specific-nfrs) +- [7. Public Library Interfaces](#7-public-library-interfaces) + - [7.1 Public API Surface](#71-public-api-surface) + - [7.2 External Integration Contracts](#72-external-integration-contracts) +- [8. Use Cases](#8-use-cases) +- [9. Acceptance Criteria](#9-acceptance-criteria) +- [10. Dependencies](#10-dependencies) +- [11. Assumptions](#11-assumptions) +- [12. Risks](#12-risks) +- [13. Open Questions](#13-open-questions) +- [14. References](#14-references) + + ## 1. Overview -**Purpose**: Type Registry provides GTS schema storage and resolution for LLM Gateway tool definitions. +### 1.1 Purpose -Type Registry is a schema catalog that stores GTS (Generic Type System) schemas for function/tool definitions. LLM Gateway queries the registry to resolve tool schema references before sending requests to providers. This enables consumers to reference tools by ID rather than embedding full schemas in every request. +Types Registry is the central platform registry for type contracts used by gears to communicate, exchange typed data, discover capabilities, and extend platform functionality. It gives gears one shared authority for type identity, schema validation, derivation compatibility, type casting/conversion, aliases, lifecycle, discovery, and resolving between user-facing type identifiers and machine-readable registry references. -The registry supports both single and batch schema lookups for efficient tool resolution when multiple tools are used in a request. +Types Registry governs contract registration and activation metadata, while owning gears remain responsible for runtime object storage and business behavior. -**Target Users**: -- **LLM Gateway** - Primary consumer for tool schema resolution +### 1.2 Background / Problem Statement -**Key Problems Solved**: -- **Schema management**: Centralized storage for tool/function schemas -- **Reference resolution**: Convert schema IDs to full GTS schemas -- **Batch lookup**: Efficient resolution of multiple tools per request +The platform currently needs shared type contracts for gear contracts, configuration, plugin discovery, and typed references between domain objects. Without a central registry, each gear would need to duplicate schema management, version compatibility, type derivation compatibility checks, type casting/conversion, alias resolution, tenant/global ownership, lifecycle rules, and cache invalidation. -**Success Criteria**: -- All scenarios (S1-S2) implemented and operational -- Schema resolution latency < 10ms P99 -- Consistent schema ID format enforced +Some vendors may already have an existing type registry or contract catalog that remains the source of truth for their contracts. Types Registry must still provide one platform-facing control plane for gears, while allowing selected registry entities to be externally managed by vendor registry sources. -**Capabilities**: -- Get schema by ID -- Batch get schemas -- Schema ID validation +Industry systems solve adjacent parts of this problem separately. Kubernetes CRDs, Azure Resource Providers, and AWS CloudFormation Registry cover controlled resource-type extension. Confluent Schema Registry, AWS Glue Schema Registry, Azure Event Hubs Schema Registry, and Google Pub/Sub Schemas cover schema compatibility and client lookup. Dataverse metadata covers tenant-facing metadata extension. Types Registry combines these patterns for the platform's type-contract control plane. + +The canonical representation of registry contracts is based on [Global Type System](https://github.com/globaltypesystem/gts-spec) (GTS) Types, GTS Type Schemas, and registered GTS Instances. + +### 1.3 Goals (Business Outcomes) + +- Provide one governed registry for platform type contracts instead of per-gear extension mechanisms. +- Allow gears to use stable machine-readable type references while preserving user-facing GTS Identifiers and aliases. +- Enable safe type evolution through compatibility checks, lifecycle state, dependency awareness, and casting. +- Support global platform types and tenant-owned custom types with predictable ownership and visibility rules. +- Federate local and external registry sources behind one platform-facing registry contract. +- Make registry lookups cacheable for SDK clients without sacrificing correctness in multi-pod deployments. + +### 1.4 Glossary + +| Term | Definition | +|------|------------| +| GTS | Global Type System: specification for globally unique, versioned type identities and JSON Schema-based type definitions. | +| GTS Type | A type entity identified by a GTS Type Identifier and defined by a GTS Type Schema. | +| GTS Type Identifier | Canonical GTS identifier ending with `~` that identifies a GTS Type. | +| GTS Type Schema | Canonical definition of a GTS Type: a JSON Schema document annotated with GTS-specific keywords and describing instance shape, traits, and derivation. | +| GTS Instance | A concrete object, value, or document that conforms to a GTS Type. | +| GTS Instance Identifier | GTS identifier without the trailing `~`, used to identify a well-known instance. | +| GTS Identifier | Canonical user-facing identifier for a GTS Type or GTS Instance. | +| Registry Reference | Machine-readable reference to a registry entity. Its storage representation is selected by a future storage identity decision. | +| Alias | Registry-managed alternate name that resolves to a GTS Type Schema or registered GTS Instance. | +| Extension Point | A platform location that can be extended by registered type contracts. | +| Extension Type Registration | Registry record that makes a GTS Type Schema available for a specific Extension Point. | +| Owning Gear | Gear that owns runtime storage and behavior for objects that use a registered type. | +| Validation Hook | Registry-governed declaration that allows an owning gear to semantically validate a registry entity before it becomes active. | +| Registry Federation | Types Registry capability to expose one platform-facing registry contract over multiple registry sources. | +| Registry Source | Source that provides registry entities to Types Registry. | +| External Registry Source | Vendor or platform-integrated registry source outside Types Registry's own authoritative storage. | +| Managed Entity | Registry entity for which Types Registry is the source of truth. | +| Externally Managed Entity | Registry entity whose definition and source-owned state are authoritative in an External Registry Source, while Types Registry governs platform visibility and usage semantics. | +| Per-Tenant Entity State | Tenant-specific effective state of a GTS Type or GTS Instance: `NOT_INITIALIZED`, `ENABLED`, `TEMPORARY_DISABLED`, `DISABLED`, or `SOFT_DELETED`. | ## 2. Actors ### 2.1 Human Actors - +#### XaaS Vendor Architect + +**ID**: `cpt-cf-types-registry-actor-xaas-vendor-architect` + +- **Role**: Chooses how Gears are composed into a vendor product and which product domains are extensible through GTS. +- **Needs**: A governed type registry that supports vendor-specific extension without forked per-gear mechanisms. + +#### Platform Developer + +**ID**: `cpt-cf-types-registry-actor-platform-developer` + +- **Role**: Defines platform GTS Type Schemas, extension points, and gear contracts. +- **Needs**: Safe registration, compatibility checks, dependency awareness, lifecycle management, and predictable startup behavior. + +#### Tenant Administrator + +**ID**: `cpt-cf-types-registry-actor-tenant-admin` + +- **Role**: Manages tenant-owned custom types and aliases exposed through authenticated platform APIs. +- **Needs**: Tenant-scoped type management, discovery of global and tenant-visible types, and protection from cross-tenant changes. ### 2.2 System Actors -#### LLM Gateway +#### Platform Gear + +**ID**: `cpt-cf-types-registry-actor-platform-gear` + +- **Role**: Registers platform Type Schemas and Instances during initialization and resolves registry references at runtime. + +#### Domain Gear + +**ID**: `cpt-cf-types-registry-actor-domain-gear` + +- **Role**: Owns runtime domain objects that refer to registered types and uses Types Registry for resolving, discovery, and query assistance. + +#### Registry Source Plugin + +**ID**: `cpt-cf-types-registry-actor-registry-source-plugin` + +- **Role**: Provides access to an External Registry Source through a platform-governed plugin contract. + +#### CI Pipeline + +**ID**: `cpt-cf-types-registry-actor-ci-pipeline` + +- **Role**: Validates type compatibility, dependency impact, and extension registrations before deployment. + +## 3. Operational Concept & Environment + +Runtime and gear architecture follow the repository-level ToolKit guidance: + +- [guidelines/README.md](../../../../guidelines/README.md) +- [docs/toolkit_unified_system/README.md](../../../../docs/toolkit_unified_system/README.md) + +Types Registry has one gear-specific operational constraint: registry state must be persistent and consistent across multi-pod deployments. Process-local state and client caches are allowed only as derived cache state. + +## 4. Scope + +### 4.1 In Scope + +- GTS Type Schema registration, retrieval, search, lifecycle, and compatibility checks. +- Registered GTS Instance registration, retrieval, search, lifecycle, validation, and casting. +- Platform extension type registration for gear-defined extension points. +- Owning-gear semantic validation hooks for registration and lifecycle activation. +- Registry federation for external registry sources and externally managed entities. +- Alias management and alias-aware resolving. +- Stable registry reference support for domain gears. +- Tenant/global ownership, visibility, and management boundaries. +- Dependency tracking for GTS and JSON Schema references. +- `gts-rust` integration for GTS parsing, validation, reference derivation, wildcard matching, compatibility, casting, and schema generation/conversion capabilities required by registry workflows. +- SDK and REST contracts for registry management, resolving, validation, casting, and discovery. +- Client-side cache correctness protocol. + +### 4.2 Out of Scope + +- Runtime storage for arbitrary domain objects owned by other gears. +- Business behavior for registered extension types. +- Authoritative management of external registry sources that remain outside the platform's ownership boundary. +- GTS namespace governance outside registration-time validation and conflict detection. +- Full audit/history of every registry mutation beyond lifecycle and dependency state required by this PRD. + +## 5. Functional Requirements + +Functional requirements define what Types Registry must provide. Design details such as DB tables, route paths, cache transport, and query planner representation are intentionally outside this PRD. + +### 5.1 Registry Core + +#### Type Schema Management + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-register-schemas` + +The system **MUST** allow authorized actors to register, retrieve, search, update lifecycle state for, and delete GTS Type Schemas, subject to validation, ownership, dependency, and compatibility rules. + +- **Rationale**: Gears need one authoritative registry for type contracts. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-tenant-admin` + +#### Instance Management + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-register-instances` + +The system **MUST** allow authorized actors to register, retrieve, search, update lifecycle state for, and delete named GTS Instances that conform to registered Type Schemas. + +- **Rationale**: Platform gears need registered well-known instances for configuration, discovery, and extension metadata. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-tenant-admin` + +#### GTS Validation + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-gts-validation` + +The system **MUST** validate GTS Identifiers, Type Schemas, Instances, references, wildcard patterns, and version semantics using the platform-approved GTS implementation. + +- **Rationale**: Registry behavior must match the GTS specification and avoid divergent local interpretations. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-ci-pipeline` + +#### Compatibility Checks + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-validate-schema-compat` + +The system **MUST** check compatibility between related or versioned GTS Type Schemas and reject registrations that would violate required compatibility policy. + +- **Rationale**: Type evolution must not silently break consumers. +- **Actors**: `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-ci-pipeline` + +#### Dependency Awareness + +- [ ] `p2` - **ID**: `cpt-cf-types-registry-fr-ref-tracking` + +The system **MUST** track dependencies between registered entities and expose impact information before deletion, incompatible changes, or lifecycle transitions that can affect dependents. + +- **Rationale**: Platform teams need predictable blast-radius analysis for type changes. +- **Actors**: `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-ci-pipeline` + +#### Registry Federation + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-registry-federation` + +The system **MUST** support multiple Registry Sources, including Types Registry's own managed storage and External Registry Sources integrated through governed platform contracts. + +- **Rationale**: Vendor products may already have authoritative type registries, but platform gears still need one Types Registry contract for resolving, discovery, validation, and extension governance. +- **Actors**: `cpt-cf-types-registry-actor-xaas-vendor-architect`, `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-registry-source-plugin` + +#### Externally Managed Entities + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-externally-managed-entities` + +The system **MUST** distinguish Managed Entities from Externally Managed Entities, **MUST** require source-owned validation from External Registry Sources, and **MUST** apply platform admission rules for visibility, lifecycle exposure, resolving, aliasing, cache/freshness, and extension-point usage before externally managed entities become usable by platform gears. + +- **Rationale**: External source ownership must not bypass platform contract governance, but Types Registry should not pretend to be the source of truth for externally managed definitions or source-owned validation. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-registry-source-plugin` + +### 5.2 Platform Extension Registry + +#### Extension Point Management + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-extension-points` + +The system **MUST** represent platform Extension Points that define where registered type contracts can be used. + +- **Rationale**: Extension mechanics must be centralized rather than reimplemented by each gear. +- **Actors**: `cpt-cf-types-registry-actor-xaas-vendor-architect`, `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-platform-gear` + +#### Extension Type Registration + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-platform-extension-types` + +The system **MUST** allow authorized actors to register a GTS Type Schema as available for a specific Extension Point, subject to ownership, lifecycle, compatibility, and visibility rules. + +- **Rationale**: New platform-level types must be introduced through a governed registry. +- **Actors**: `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-tenant-admin` + +#### Behavior Boundary + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-extension-behavior-boundary` + +The system **MUST** distinguish registered type contracts from runtime behavior and domain object storage owned by other gears. + +- **Rationale**: Types Registry must remain a registry and control-plane authority, not a universal runtime object store. +- **Actors**: `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-platform-developer` + +#### Owning-Gear Semantic Validation + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-validation-hooks` + +The system **MUST** support registry-governed validation hooks that allow owning gears to accept or reject registration and lifecycle activation of registry entities based on domain-specific semantic rules before those entities become active. + +- **Rationale**: Some extension contracts cannot be validated by GTS schema rules alone; the owning gear may need to enforce domain semantics while Types Registry remains the central control-plane authority. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-platform-developer` + +### 5.3 References, Aliases, And Queries + +#### Alias Management + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-aliasing` + +The system **MUST** allow multiple aliases per GTS Type Schema and per registered GTS Instance, and **MUST** provide management and resolving behavior for aliases. + +- **Rationale**: Users and gears need stable alternate names without duplicating registry entities. +- **Actors**: `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-tenant-admin`, `cpt-cf-types-registry-actor-domain-gear` + +#### Reference And Identifier Resolution + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-id-resolution` + +The system **MUST** resolve between user-facing identifiers, aliases, machine-readable registry references, entity kind, ownership scope, and lifecycle state for both single and batch lookups. + +- **Rationale**: Domain gears need stable references for stored data and human-readable identifiers for APIs, logs, and operator workflows. +- **Actors**: `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-platform-gear` + +#### Type Query Assistance + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-type-query-assistance` + +The system **MUST** help domain gears translate user-facing type filters, including aliases, compatible versions, and GTS wildcard patterns, into registry-aware query constraints suitable for gear-owned data. + +- **Rationale**: Query behavior must be consistent even though runtime objects are stored outside Types Registry. +- **Actors**: `cpt-cf-types-registry-actor-domain-gear` + +### 5.4 Ownership, Lifecycle, And Caching + +#### Tenant And Global Ownership + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-tenant-ownership` + +The system **MUST** support platform-global registry entries and tenant-owned registry entries with explicit visibility, management, and conflict rules. + +- **Rationale**: Platform types and tenant customizations must coexist without cross-tenant leakage or accidental global mutation. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-tenant-admin` + +#### Lifecycle Management + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-lifecycle` + +The system **MUST** expose lifecycle states for Type Schemas, Instances, aliases, and extension registrations, and resolution/search behavior **MUST** respect lifecycle state. + +- **Rationale**: Type evolution needs controlled activation, deprecation, and removal. +- **Actors**: `cpt-cf-types-registry-actor-platform-developer`, `cpt-cf-types-registry-actor-tenant-admin` + +#### Per-Tenant Entity State + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-tenant-entity-state` + +The system **MUST** support per-tenant state for GTS Types and GTS Instances with the states `NOT_INITIALIZED`, `ENABLED`, `TEMPORARY_DISABLED`, `DISABLED`, and `SOFT_DELETED`. For Managed Entities, Types Registry **MUST** allow authorized actors to manage this state. For Externally Managed Entities, Types Registry **MUST** obtain tenant state from the External Registry Source before tenant-specific usability decisions. + +- **Rationale**: Entity availability can differ per tenant, and externally managed tenant state must remain authoritative in the owning source. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear`, `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-tenant-admin`, `cpt-cf-types-registry-actor-registry-source-plugin` + +#### Casting + +- [ ] `p2` - **ID**: `cpt-cf-types-registry-fr-casting` + +The system **MUST** support casting supplied instance content between compatible GTS Type Schema versions and report incompatible casts as structured failures. + +- **Rationale**: Consumers need a central, consistent way to migrate or interpret versioned typed content. +- **Actors**: `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-platform-developer` + +#### Client-Side Cache Correctness + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-client-cache` + +The system **MUST** define cache metadata and invalidation semantics that allow SDK clients to cache registry lookup and resolution results correctly across registry mutations. + +- **Rationale**: Registry lookups are common on startup and hot paths; caching must not return stale type authority. +- **Actors**: `cpt-cf-types-registry-actor-domain-gear`, `cpt-cf-types-registry-actor-platform-gear` + +#### Initialization Registration + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-two-phase-init` + +The system **MUST** support platform gear startup registration before the registry is fully ready, and **MUST** validate the complete startup registry state before publishing ready state. + +- **Rationale**: Platform gears can have interdependent type definitions that must be registered before full validation. +- **Actors**: `cpt-cf-types-registry-actor-platform-gear` + +## 6. Non-Functional Requirements + +### 6.1 Gear-Specific NFRs + +#### Lookup Latency + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-nfr-lookup-latency` + +The system **MUST** resolve an exact registry reference, GTS Identifier, or alias lookup within 10ms at p95 under normal production load. + +- **Threshold**: p95 < 10ms for exact lookup. +- **Rationale**: Registry resolving is used by gear startup and runtime paths. + +#### Query Latency + +- [ ] `p2` - **ID**: `cpt-cf-types-registry-nfr-query-latency` + +The system **MUST** return common filtered registry searches within 100ms at p95 under normal production load. + +- **Threshold**: p95 < 100ms for bounded registry search results. +- **Rationale**: Discovery and management views must remain responsive. + +#### Multi-Pod Correctness + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-nfr-multi-pod-correctness` + +The system **MUST** preserve registry correctness when multiple Types Registry pods serve reads and writes concurrently. + +- **Threshold**: No accepted write can remain permanently invisible to other pods or SDK cache validation. +- **Rationale**: Production deployments are horizontally scaled. + +#### Cache Correctness + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-nfr-cache-correctness` + +The system **MUST** prevent SDK clients from treating invalidated registry lookup results as current after a relevant registry mutation is observed. + +- **Threshold**: Integration tests cover mutation, cache validation, and stale-entry rejection. +- **Rationale**: Client-side caching is required but cannot weaken type authority. + +## 7. Public Library Interfaces + +### 7.1 Public API Surface + +#### SDK Contract + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-interface-sdk` + +- **Type**: Rust SDK trait and models. +- **Stability**: unstable until first platform-stable release. +- **Description**: In-process and remote-client contract for gear-to-gear registration, resolving, discovery, compatibility, casting, cache validation, extension registration, and externally managed entity access. +- **Breaking Change Policy**: Breaking changes allowed before first stable release; afterwards require versioned contract. + +#### REST API + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-interface-rest` + +- **Type**: Authenticated REST API. +- **Stability**: unstable until first platform-stable release. +- **Description**: External and tenant-facing contract for management, discovery, resolving, aliasing, validation, casting, cache state, extension registration, and externally managed entity visibility. +- **Breaking Change Policy**: Breaking changes allowed before first stable release; afterwards require versioned API. + +### 7.2 External Integration Contracts + +#### GTS Implementation + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-contract-gts-rust` + +- **Direction**: required by Types Registry. +- **Protocol/Format**: Rust library API. +- **Compatibility**: Types Registry relies on the approved GTS implementation for parsing, normalization, reference derivation, wildcard matching, validation, compatibility, and casting semantics. + +#### Platform AuthN/AuthZ + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-contract-platform-auth` + +- **Direction**: required by Types Registry. +- **Protocol/Format**: ToolKit SecurityContext, PolicyEnforcer, and platform authentication/authorization contracts. +- **Compatibility**: Tenant/global ownership checks must follow platform-level AuthN/AuthZ rules. + +#### ToolKit Plugin Architecture + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-contract-toolkit-plugins` + +- **Direction**: required by Types Registry for external registry source integration. +- **Protocol/Format**: ToolKit plugin and scoped ClientHub contracts. +- **Compatibility**: External Registry Sources must be integrated behind Types Registry rather than consumed directly by regular gears. + +## 8. Use Cases + +#### Register A Platform Extension Type + +- [ ] `p1` - **ID**: `cpt-cf-types-registry-usecase-register-extension-type` + +**Actor**: `cpt-cf-types-registry-actor-platform-developer` + +**Preconditions**: +- An Extension Point exists. +- A GTS Type Schema is available for registration. -**ID**: `cpt-cf-types-registry-actor-llm-gateway` +**Main Flow**: +1. Actor registers the GTS Type Schema. +2. Actor registers the Type Schema as available for the Extension Point. +3. Types Registry validates identity, ownership, compatibility, lifecycle, conflicts, and any required owning-gear semantic validation. +4. Owning gears can discover the extension type and use its registry reference in their own data. -**Role**: Resolves tool schema references to full GTS schemas before provider calls. +**Postconditions**: +- The extension type is discoverable and governed by Types Registry. -## 3. Functional Requirements +#### Resolve A User-Facing Type Filter For Gear-Owned Data -#### Get Schema by ID +- [ ] `p1` - **ID**: `cpt-cf-types-registry-usecase-resolve-type-filter` -- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-get-schema-v1` +**Actor**: `cpt-cf-types-registry-actor-domain-gear` -The system must resolve a schema ID to full GTS schema for LLM Gateway tool resolution. +**Preconditions**: +- The gear owns runtime objects that reference registry entities. +- A caller supplies a GTS Identifier, alias, compatible-version expression, or wildcard pattern. -**Actors**: `cpt-cf-types-registry-actor-llm-gateway` +**Main Flow**: +1. Gear asks Types Registry to resolve the user-facing type filter. +2. Types Registry applies alias, ownership, lifecycle, version, and wildcard rules. +3. Gear receives registry-aware query constraints and applies them to its own storage. -#### Batch Get Schemas +**Postconditions**: +- The gear returns domain objects using consistent registry semantics without depending on one specific registry-reference storage representation. -- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-batch-get-schemas-v1` +#### Use An Externally Managed Entity -The system must resolve multiple schema IDs in a single request for efficient multi-tool resolution. +- [ ] `p1` - **ID**: `cpt-cf-types-registry-usecase-use-externally-managed-entity` -**Actors**: `cpt-cf-types-registry-actor-llm-gateway` +**Actor**: `cpt-cf-types-registry-actor-domain-gear` -#### Schema ID Validation +**Preconditions**: +- An External Registry Source is available through a governed Registry Source Plugin. +- The external source provides a registry entity that is visible to the platform. -- [ ] `p1` - **ID**: `cpt-cf-types-registry-fr-validate-schema-id-v1` +**Main Flow**: +1. Types Registry obtains the externally managed entity definition from the External Registry Source. +2. Types Registry requires source-owned validation from the External Registry Source and applies platform admission rules for visibility, lifecycle exposure, aliases, cache/freshness, and extension-point usage. +3. Types Registry obtains the entity's effective per-tenant state from the External Registry Source when the caller needs tenant-specific usability. +4. The domain gear resolves or discovers the entity through the normal Types Registry SDK or REST contract. -The system must validate schema ID format before lookup. +**Postconditions**: +- The domain gear uses the entity through Types Registry without directly depending on the External Registry Source. -**Actors**: `cpt-cf-types-registry-actor-llm-gateway` +#### Validate A Type Evolution Before Deployment -## 4. Use Cases +- [ ] `p2` - **ID**: `cpt-cf-types-registry-usecase-validate-type-evolution` -#### UC-001: Get Schema by ID +**Actor**: `cpt-cf-types-registry-actor-ci-pipeline` -- [ ] `p1` - **ID**: `cpt-cf-types-registry-usecase-get-schema-v1` -**Actor**: `cpt-cf-types-registry-actor-llm-gateway` +**Preconditions**: +- A Type Schema change is proposed. -**Preconditions**: Schema exists in registry. +**Main Flow**: +1. CI checks the proposed Type Schema against existing registered state. +2. Types Registry reports compatibility, dependency impact, and lifecycle conflicts. +3. CI accepts or blocks the deployment based on registry results. -**Flow**: -1. LLM Gateway sends get_schema(schema_id) -2. Type Registry validates schema ID format -3. Type Registry looks up schema -4. Type Registry returns GTS schema +**Postconditions**: +- Incompatible or unsafe type changes are detected before rollout. -**Postconditions**: Schema returned or error. +## 9. Acceptance Criteria -**Acceptance criteria**: -- Returns schema_not_found if ID does not exist -- Returns invalid_schema_id if format is wrong -- Schema ID format: `gts.cf.core.faas.func.v1~....v1` +- [ ] Platform gears can register GTS Type Schemas and registered Instances during startup and reach ready state only after validation succeeds. +- [ ] A new platform extension type can be introduced through Types Registry without adding a bespoke extension registry to its owning gear. +- [ ] An owning gear can block activation of an invalid extension contract through a registry-governed semantic validation hook. +- [ ] An externally managed entity can be discovered and resolved through Types Registry without direct dependency on its External Registry Source. +- [ ] Tenant-specific usability decisions respect per-tenant entity state for both Managed Entities and Externally Managed Entities. +- [ ] Domain gears can use stable registry references and resolve user-facing GTS Identifiers, aliases, compatible-version filters, and wildcard patterns through Types Registry. +- [ ] Tenant-owned entries are isolated from other tenants while remaining able to reference visible global entries. +- [ ] Compatibility, dependency, lifecycle, and cache invalidation behavior is testable through SDK and REST contracts. -#### UC-002: Batch Get Schemas +## 10. Dependencies -- [ ] `p1` - **ID**: `cpt-cf-types-registry-usecase-batch-get-schemas-v1` -**Actor**: `cpt-cf-types-registry-actor-llm-gateway` +| Dependency | Description | Criticality | +|------------|-------------|-------------| +| [GTS specification](https://github.com/globaltypesystem/gts-spec) | Defines canonical GTS identity, type/instance terminology, validation, derivation, compatibility, and reference semantics | `p1` | +| gts-rust | Platform-approved implementation of GTS parsing, validation, compatibility, reference derivation, wildcard, casting, and schema generation/conversion behavior | `p1` | +| ToolKit SDK/ClientHub | Gear-to-gear contract and client registration mechanism | `p1` | +| ToolKit plugin architecture | Plugin isolation and scoped client pattern for Registry Source Plugins | `p1` | +| Platform AuthN/AuthZ | Tenant/global access control and SecurityContext propagation | `p1` | +| Persistent platform database | Authoritative registry state for multi-pod deployments | `p1` | -**Preconditions**: At least one schema ID provided. +## 11. Assumptions -**Flow**: -1. LLM Gateway sends get_schemas([schema_id, ...]) -2. Type Registry validates all schema IDs -3. Type Registry looks up all schemas -4. Type Registry returns array of GTS schemas +- GTS remains the canonical platform type identity model. +- Runtime domain objects remain owned by their domain gears, not by Types Registry. +- Gears use Types Registry for resolving and query assistance; the concrete storage representation for gear-owned references is intentionally left to a future design decision. +- External Registry Sources may remain authoritative for externally managed entities, but platform gears access those entities through Types Registry. +- Industry analogues are used as design inputs by pattern, not as direct product copies. -**Postconditions**: Schemas returned (partial success supported). +## 12. Risks -**Acceptance criteria**: -- Single request for multiple tools -- Partial success: returns found schemas, errors for missing -- More efficient than multiple single lookups +| Risk | Impact | Mitigation | +|------|--------|------------| +| Types Registry scope expands into a universal object store | Ownership confusion and excessive complexity | Keep runtime object storage and business behavior explicitly out of scope | +| Alias and wildcard semantics are underspecified | Inconsistent query and cache behavior across gears | Capture alias and query-planning rules before implementation | +| Cache protocol is too weak for multi-pod deployments | Stale type resolution in long-running clients | Make cache correctness a first-class requirement and integration-test mutation scenarios | +| Extension model is too generic | Hard-to-use registry that does not fit concrete platform domains | Validate first design iterations against representative extension domains from target gears | +| Semantic validation hooks become an execution framework | Security, latency, and ownership complexity | Keep hooks as governed validation contracts owned by gears; define execution, AuthN, timeout, and failure policy before implementation | +| External sources bypass platform governance | Inconsistent contracts, resolving, or visibility across gears | Require externally managed entities to pass platform admission before use by gears | +| Externally managed tenant state is cached without strong invalidation | Tenants may see entities as enabled after the source disabled or soft-deleted them | Keep external tenant state source-owned and define live lookup or explicit invalidation guarantees before implementation | -## 5. Non-functional requirements +## 13. Open Questions -#### N/A +- What are the initial Extension Points required for the first release? +- Are tenant-owned extension types allowed for all Extension Points or only for an allowlist? +- What alias uniqueness scope and precedence rules are required? +- What form should type query assistance return to domain gears: concrete reference set, normalized predicate, or opaque query plan? +- What lifecycle states are required for the first release? +- Which registry entity kinds and lifecycle transitions require owning-gear semantic validation in the first release? +- Which external registry source capabilities are required in the first release: read-only discovery, synchronization, validation, or delegated writes? -- [ ] `p1` - **ID**: `cpt-cf-types-registry-nfr-na` +## 14. References - +- **GTS spec**: [Global Type System](https://github.com/globaltypesystem/gts-spec) +- **ToolKit**: [docs/toolkit_unified_system/README.md](../../../../docs/toolkit_unified_system/README.md) +- **ToolKit plugins**: [docs/TOOLKIT_PLUGINS.md](../../../../docs/TOOLKIT_PLUGINS.md)