Initial public ModelForge release

docs/architecture/DOMAIN_MODEL.md

@@ -0,0 +1,168 @@
+# 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.