ModelForge/docs/architecture/DOMAIN_MODEL.md

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.