# Domain Model

The implementation-ready field, cardinality, mutability, deletion and cross-plane contracts are
normative in `M0_FOUNDATION_CONTRACTS.md`. The SQLAlchemy mapping and Alembic baseline are the
executable persistence form of this model.

## Core entities

### Model

Logical upstream model family/reference. Does not imply a downloadable or runnable artifact.

Important fields:

- stable internal ID
- display name
- upstream provider/source
- model family
- modalities/tasks
- parameter metadata
- upstream license metadata

### ModelRevision

An immutable upstream revision, preferably resolved to a concrete commit SHA.

Fields include:

- model ID
- upstream revision name supplied by discovery
- resolved commit SHA
- discovery timestamp
- upstream metadata snapshot

### ModelArtifact

Concrete downloaded files associated with a revision.

- storage location
- content digests
- serialization format
- size
- security state
- license state
- provenance

### DerivedArtifact

A locally generated quantization/conversion/merge derived from one immutable source artifact.

Examples:

- AWQ 4-bit
- GGUF Q4_K_M
- GGUF Q5_K_M

Derived artifacts must maintain lineage to their source.

### RuntimeProfile

The reproducible execution configuration:

- runtime type and version/image digest
- artifact variant
- quantization interpretation
- context policy
- concurrency/batch settings
- GPU-memory policy
- launch arguments
- environment constraints

### Deployment

Runnable combination of revision + artifact + runtime profile assigned to one or more capabilities/channels.

### Capability

Logical function requested by projects, such as `rag.embedding`, `vision.embedding` or `speech.transcription`.

### CapabilityContract

Versioned semantics for a capability:

- accepted input/output schema
- quality metrics
- required modalities/languages
- SLOs
- upgrade class
- migration compatibility
- fallback semantics

### Project

ModelForge consumer, e.g. ExampleRAG or ExampleVision.

### ProjectBinding

Maps a project to a capability contract and deployment channel, plus priorities, benchmark suites and migration support.

### ComputeNode

Machine capable of hosting one or more inference workers.

It has stable identity distinct from hostname, an observation source, agent protocol/version and
capabilities, central liveness state, heartbeat/inventory/telemetry timestamps, role/labels and
explicit production/lab/benchmark eligibility. Enrollment and node credentials are separate
hash-only security records; they are not node identity.

### Accelerator

GPU/accelerator attached to a compute node.

### ResourceEnvelope

Measured runtime behavior for a deployment under a test profile:

- context length
- concurrency
- cold/warm load time
- idle VRAM
- peak VRAM
- TTFT
- throughput
- p50/p95/p99 latency
- power/temperature
- OOM/failure behavior

### BenchmarkSuite

Versioned benchmark cases and scoring rules.

### BenchmarkRun

Immutable execution record tying a suite revision to a deployment and environment fingerprint.

### Experiment

Human-driven or automatic A/B comparison. May graduate individual cases into a benchmark suite.

### Recommendation

Advisor output with structured evidence, blockers, regressions, migration cost and confidence.

### Promotion

Audited action changing deployment channel state.

### Migration

Controlled process required when an upgrade changes persistent derived data or output schemas.

### AuditEvent

Append-only record of security-sensitive and operationally meaningful actions.

Audit events include actor, action, resource, outcome, correlation ID, UTC occurrence time, structured
details and previous/current event hashes. Update and delete are rejected by the persistence layer.

## Key invariants

1. Approved model revisions and artifacts are immutable.
2. Deployments reference immutable revision/artifact identities.
3. A project binds to a capability contract, not a path or model repository name.
4. Every stable deployment has local validation and benchmark evidence; M0 defines no production waiver.
5. `requires_reindex` changes must create a migration; direct promotion is invalid.
6. Deletion cannot proceed while a live binding, rollback target, migration, benchmark evidence, or lineage dependency requires the artifact.
7. Storage URIs are mutable locators; revision SHA and artifact digests are immutable identities.
8. Promotion and migration are distinct records and a promotion never implies completed data migration.