M0 Foundation Contracts

This document is the implementation-level boundary for M0. The executable forms live in domain/contracts.py, domain/lifecycle.py, persistence/models.py, the Alembic baseline, and validated manifests under config/.

Product and trust boundaries

Plane	Owns	Must not own
Control plane	registry, policy, provenance, lifecycle decisions, audit, evidence	inference execution or arbitrary hub code
Gateway	project authentication, capability/channel resolution, QoS, normalized errors	direct artifact selection by projects
Runtime plane	adapter-governed load/probe/infer/unload against approved read-only artifacts	public endpoints, project/HF secrets, Docker socket, default egress
Hardware plane	node/accelerator identity, inventory and measured telemetry	lifecycle or routing decisions
Hugging Face boundary	discovery metadata and quarantined acquisition by exact revision	approval, deployment or trust decisions
Project boundary	declares versioned capabilities, SLO, priority, fallback and migration support	model repository names, paths or runtime endpoints
Runtime-engine boundary	implements the internal adapter contract	leaking engine-specific behavior into capability contracts

ModelForge is not a cloud-AI broker, Kubernetes platform, training cluster, generic chatbot, or public multi-user inference service. There is no implicit cloud fallback.

Identity, cardinality and lifecycle

IDs are UUIDs in persistence; manifest keys are stable human-readable identities.
Model 1—N ModelRevision 1—N ModelArtifact 1—N DerivedArtifact preserves source lineage.
A Deployment references exactly one revision, exactly one source-or-derived artifact and an immutable runtime profile. Composite foreign keys prevent the artifact revision from diverging.
Capability 1—N CapabilityContract; project bindings reference a contract version and channel, never a model.
ComputeNode 1—N Accelerator; leases and envelopes remain node-ready while M1/M6 optimize for one GPU.
Benchmark runs, promotions, migrations and lineage references use restrictive deletion. Lifecycle removal is deprecation followed by dependency-checked archival; it is never cascade cleanup.
Approved revisions, verified artifacts, runtime profiles, benchmark runs, promotions and audit events are immutable records. Mutable labels and operational status are separate fields.
All timestamps are timezone-aware UTC database timestamps.

Capability and project contract

Capability contracts version JSON input/output schemas, modalities, language support, streaming, structured output, vector dimensionality/normalization semantics, SLOs, quality metrics, upgrade class, fallback, privacy and resource requirements. Vector-producing contracts with unproven cross-deployment compatibility are rejected unless classified requires_reindex.

Project manifests select a capability contract version plus stable/candidate/experimental channel, priority, optionality, explicit fallback, migration support, project SLO and benchmark suites. The strict schemas reject unknown fields, including attempts to add a concrete model ID.

Artifact proof

The reproducibility chain is:

upstream repository + resolved commit SHA → filename/type + SHA-256 → optional source digest + derivation tool/version/arguments → runtime-profile fingerprint → deployment → benchmark run.

Storage locations are locators, not identities. The digest and immutable lineage provide identity. A derived artifact is invalid without its source digest and conversion tool/version.

Runtime adapter contract

An adapter validates a runtime profile, probes layered health, loads only under a scheduler lease and unloads by deployment identity. Profiles capture runtime type/version, image digest, artifact digest, quantization, context, concurrency, launch arguments, environment constraints and security toggles. The control plane depends on this protocol rather than vLLM, Transformers, Diffusers or llama.cpp. Concrete adapters belong to M5.

Scheduler contract

Lease requests carry deployment, priority, residency (always_warm, TTL-based keep_warm, load_on_demand, exclusive, lab_only), measured resource envelope, warm TTL, exclusivity and explicit CPU-fallback permission. Envelopes are scoped by accelerator kind, context, concurrency and batch size and include idle/peak VRAM plus safety margin. A lease moves through requested/acquired/ released state. Failure must release reservations and emit a structured event. M6 implements policy; M0 does not pretend to schedule work.

Benchmark comparability

A run binds deployment, revision SHA, artifact digest, runtime/version/image, launch arguments, suite and dataset revisions, CUDA, driver, accelerator identity, context, concurrency, seed, timestamps and a deterministic environment digest. Runtime, driver/CUDA, accelerator or launch profile changes make cross-environment comparisons non-comparable. Historical evidence is retained with a stale reason; it is never rewritten.

Promotion and migration

Promotion is a human-approved routing/lifecycle action backed by verified artifact state, local and project benchmark IDs and a rollback deployment. Migration is separate. For embeddings, promotion is blocked until a migration is ready after: current index → distinct shadow index → backfill → validation → shadow queries/benchmarks → atomic cutover. The prior index and deployment remain until the recorded rollback-retention deadline.

Failure ownership and health

The normalized codes are MODEL_LOAD_FAILED, GPU_OOM, RUNTIME_CRASH, TIMEOUT, INVALID_OUTPUT, HEALTHCHECK_FAILED, ARTIFACT_CORRUPT, DRIVER_ERROR and CAPABILITY_UNAVAILABLE. Runtime adapters own load/crash/output faults; the scheduler owns capacity, OOM reservation and lease recovery; the gateway owns timeout and approved fallback/degrade behavior; the control plane owns artifact corruption, deployment blocking and audit; an operator owns explicit security exceptions and hard production promotion decisions. Retries must be bounded and observable.

Health is reported separately for process, runtime, model smoke inference, capability contract/routing, and required project capabilities. Process liveness alone cannot make a deployment healthy.

6.3 KiB Raw Blame History