Initial public ModelForge release

2026-09-01 21:30:16 +02:00
commit 7082ab955a
490 changed files with 104252 additions and 0 deletions
@@ -0,0 +1,26 @@
+# GPU Resource Accounting
+
+M10 treats NVML as physical truth while retaining ModelForge attribution as a separate logical
+ledger. A resident model is already present in `observed_used_vram_bytes` and must therefore never
+be subtracted a second time.
+
+```text
+physical_used = max(observed_nvml_used, attributed_managed_resident)
+unmanaged_external = max(0, observed_nvml_used - attributed_managed_resident)
+future_lease = max(0, reserved_bytes - materialized_bytes)
+schedulable = max(0, total - physical_used - future_leases - dynamic_reserve)
+```
+
+Every term is non-negative. The exposed invariant delta is
+`observed - managed_resident - unmanaged_external`; it diagnoses sampling or attribution drift but
+is never converted into capacity. `KNOWN`, `ESTIMATED`, and `UNKNOWN` describe attribution quality.
+Unknown or stale telemetry fails closed with zero schedulable capacity; it never means zero use.
+
+The versioned `m10-v1` reserve is the maximum of 1 GiB, 5% of total VRAM, and a 256 MiB runtime
+margin. A deployment requires its measured peak plus the maximum of 128 MiB or 10% of that peak.
+Only unmaterialized leases reduce future headroom. Accelerator-row locking makes the database the
+coordination boundary for concurrent admissions.
+
+Resource envelopes remain bound to the exact artifact, runtime profile, accelerator and environment
+fingerprint. A stale or mismatched heavy envelope cannot authorize placement. Persistent history is
+bounded placement evidence, not a one-second telemetry archive.