Skip to content

ClassID → Model Pool Architecture (v1)

Executive Summary

A curated, versioned ClassID → Model Pool mapping system for verdikta-common that provides arbiters and client developers with a single source of truth for AI model capabilities, limits, and validation rules.

Key Benefits: - Deterministic validation and truncation of Query Manifests - Strict model identifier pinning (no floating versions) - Built-in resource limits and governance - Type-safe TypeScript API

Core Components

1. Data Model

ClassID Space: - Tracked range: 0 ... 2^56-1 (curated by Verdikta core) - Reserved range: ≥ 2^56 (open for experimental use) - Hard collision prevention via CI

Class Structure:

interface ClassSpec {
  id: bigint;
  status: 'ACTIVE' | 'DEPRECATED' | 'EMPTY';
  name: string;
  description?: string;
  models: ModelEntry[];
  limits: ClassLimits;
  deprecation: DeprecationInfo | null;
}

Resource Limits: - max_outcomes: Maximum evaluation outcomes (20) - max_panel_size: Maximum unique models per panel (5)
- max_iterations: Maximum panel cycles (3) - max_evidence_payload_bytes: Total file size limit (40MB) - max_supporting_files: Maximum file count (10) - max_single_file_bytes: Per-file size limit (20MB)

2. Initial Seed Classes

ClassID Name Models Status
128 OpenAI & Anthropic Core gpt-5, gpt-5-mini, claude-sonnet-4 ACTIVE
129 Open-Source Local (Ollama) llama3.1:8b, llava:7b, deepseek-r1:8b, qwen3:8b ACTIVE
130 OSS via Hyperbolic API (reserved) EMPTY

3. Public API

Core Functions:

// Class resolution
getClass(classId: number|bigint): ClassSpec|undefined
isReserved(classId: number|bigint): boolean
isTracked(classId: number|bigint): boolean

// Discovery
listClasses(filter?: {status?, provider?}): ClassSpec[]

// Validation with deterministic truncation
validateQueryAgainstClass(queryManifest: any, classId: number|bigint): ValidationResult

ValidationResult Structure:

interface ValidationResult {
  ok: boolean;                    // Usable after truncations
  classKnown: boolean;           // Class exists in map
  classStatus: ClassStatus|null; // For deprecation warnings
  issues: Issue[];               // Machine/human readable issues
  effectiveManifest: any|null;   // Truncated manifest to execute
}

Key Design Decisions

1. Deterministic Truncation Strategy

Instead of rejecting oversized manifests, apply deterministic truncation:

  1. Outcomes: Keep first max_outcomes by declared order
  2. Panel Models: Remove duplicates, then keep first max_panel_size
  3. Iterations/Counts: Clamp to maximum values
  4. Files: Drop oversized files, then truncate by stable priority (support files first, then additional files by manifest order)

2. Strict Model Pinning

  • No floating versions (e.g., -latest)
  • Exact provider/model identifier pairs
  • CI enforcement of pinning policy

3. Governance Model

  • Verdikta core team controls tracked range (< 2^56)
  • Community PRs welcome but gated
  • Semantic versioning for compatibility

4. Error Handling Philosophy

  • Unknown ClassID: Fail fast with UNKNOWN_CLASS
  • Empty Classes: Block usage until populated
  • Deprecated Classes: Warn but allow until grace period expires

Implementation Structure

src/
├── classmap/
│   ├── index.ts           # Public API exports
│   ├── types.ts           # TypeScript interfaces
│   ├── validator.ts       # Validation & truncation logic
│   └── utils.ts          # Helper functions
├── data/
│   └── classmap.v1.json  # Seed data
└── schemas/
    └── classmap.v1.json  # JSON schema

CI/Quality Gates

Automated Checks: 1. JSON schema validation 2. ClassID uniqueness verification
3. No redefinition of populated classes (without maintainer override) 4. Strict pinning enforcement (reject *latest* patterns) 5. Provider validation 6. Version bump requirement for map changes

Integration Points

Arbiter Nodes

  • Registration: Verify ClassID is ACTIVE before staking
  • Runtime: Execute effectiveManifest (not original) for consistency

Client Applications

  • UI: Use getClass() to show supported models
  • Preflight: Use validateQueryAgainstClass() to preview truncations

Versioning Strategy

  • Minor bump: Adding classes, relaxing limits
  • Major bump: Tightening limits, breaking changes
  • Patch: Documentation, non-functional metadata

Out of Scope (v1)

  • On-chain class records
  • IPFS pointers for class definitions
  • MIME-type allowlists per model
  • Authoring CLI tools
  • Automatic model capability discovery

Success Metrics

  1. Determinism: Identical truncation across all arbiters
  2. Type Safety: Full TypeScript coverage with strict types
  3. Governance: Clean PR process with automated quality gates
  4. Performance: Sub-millisecond validation for typical manifests
  5. Adoption: Integration in both arbiter nodes and client SDKs

This architecture provides a solid foundation for v1 while maintaining flexibility for future enhancements like per-model MIME allowlists, cost hints, and richer capability metadata.