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:
- Outcomes: Keep first
max_outcomes
by declared order - Panel Models: Remove duplicates, then keep first
max_panel_size
- Iterations/Counts: Clamp to maximum values
- 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¶
- Determinism: Identical truncation across all arbiters
- Type Safety: Full TypeScript coverage with strict types
- Governance: Clean PR process with automated quality gates
- Performance: Sub-millisecond validation for typical manifests
- 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.