102 lines
6.3 KiB
Markdown
102 lines
6.3 KiB
Markdown
# 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.
|