neuron-tai/packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json

{
  "schema_version": 1,
  "contract_version": 1,
  "contract_id": "dgr-alpha-beta-performance/v1",
  "locked_at": "2026-07-22",
  "locked_by": "DGR-019",
  "locked_before_target_execution": true,
  "prompt_set": {
    "id": "dgr-fixed-prompt-set-v1",
    "prompts": [
      {
        "id": "short-instruction",
        "text": "Summarize the following changelog entry in one sentence: Added distributed layer-range execution for GGUF shards using range-aware tensor ownership.",
        "context_class": "short"
      },
      {
        "id": "code-completion",
        "text": "def fibonacci(n):\n    \"\"\"Return the nth Fibonacci number.\"\"\"\n",
        "context_class": "short"
      },
      {
        "id": "multi-step-reasoning",
        "text": "A route has three shards, each holding a contiguous layer range. If shard A owns layers 0-13, shard B owns layers 14-27, and shard C owns layers 28-42, how many layers does each shard own and which shard is the tail?",
        "context_class": "short"
      },
      {
        "id": "long-context-fill",
        "text": "Repeat the phrase 'the route holds a contiguous layer range' 1024 times, then answer: which node owns the tail?",
        "context_class": "long",
        "notes": "Beta long-context lane only; the driver expands this template to the locked context_tokens length rather than the literal text carrying that many tokens in this document."
      }
    ]
  },
  "sampling": {
    "temperature": 0.0,
    "top_p": 1.0,
    "top_k": 1,
    "seed": 1234,
    "notes": "Greedy by construction, matching meshnet_node.recipe_benchmark.SamplingPolicy defaults: sampling noise must never be indistinguishable from a quantization, transport, or batching effect."
  },
  "lanes": {
    "controlled-safetensors": {
      "role": "reference recipe",
      "locked_elsewhere": true,
      "contract_module": "meshnet_node.performance_contract",
      "contract_id": "dgr-001-controlled-whole-model-baseline-v1",
      "contract_schema_version": 1,
      "notes": "Already locked by DGR-001/performance_contract.py (contract_version=1, immutable ContractThresholds). This document does not re-lock or duplicate those thresholds; it references them so the four lanes are enumerated in one place."
    },
    "whole-model-gguf": {
      "role": "single-node quantization/model-fit comparison against controlled-safetensors",
      "locked_elsewhere": true,
      "contract_module": "meshnet_node.performance_contract",
      "contract_id": "dgr-001-controlled-whole-model-baseline-v1",
      "contract_schema_version": 1,
      "notes": "Same locked contract as controlled-safetensors; this is the reference recipe's counterpart lane, not a separate threshold set."
    },
    "dense-distributed-gguf": {
      "role": "multi-shard Meshnet Inference Route running a dense (non-MoE) architecture's GGUF weights across a real multi-machine route via the ShardEngine/native worker",
      "reference_baseline": "the existing production Meshnet distributed Route Session running the same dense model over safetensors on the same node topology and network",
      "prompt_ids": [
        "short-instruction",
        "code-completion",
        "multi-step-reasoning"
      ],
      "context_tokens": 2048,
      "output_tokens": 128,
      "concurrency_levels": [
        1,
        4
      ],
      "hardware": {
        "topology": "named certification scenario only: 2-4-stage or 10-plus-stage real multi-machine route",
        "network": "same LAN/WAN class as the existing production route it is compared against",
        "device_class": "generic; not hardcoded to one backend. CPU/CUDA/ROCm/Vulkan/Metal lanes are certified separately per RALPH-CONTEXT.md and only advertised once real-hardware-certified"
      },
      "metrics": [
        "ttft_p50_ms",
        "ttft_p95_ms",
        "prefill_tokens_per_sec",
        "decode_tokens_per_sec",
        "aggregate_decode_tokens_per_sec",
        "latency_p50_ms",
        "latency_p95_ms",
        "seam_bytes",
        "seam_latency_ms",
        "queue_wait_ms",
        "peak_rss_bytes",
        "peak_vram_bytes",
        "failures"
      ],
      "certification_scenarios": {
        "stage_count": [
          "2-4-stage",
          "10-plus-stage"
        ],
        "quantization": [
          "Q4_K_M",
          "Q8_0",
          "bf16-reference"
        ]
      }
    },
    "v4-flash-distributed": {
      "role": "full DeepSeek V4 Flash (43 main layers plus reserved MTP; mHC 4x4096 boundary; 256 routed + 1 shared experts, six routed active) distributed route across a named certification stage-count scenario, MTP reserved and off",
      "reference_baseline": "the existing production Meshnet distributed Route Session running DeepSeek V4 Flash over safetensors on the same node topology and network, where available; otherwise dense-distributed-gguf runtime/transport overhead is reported as an explicit limitation until DGR-044 pins a safetensors V4 baseline",
      "prompt_ids": [
        "short-instruction",
        "code-completion",
        "multi-step-reasoning"
      ],
      "alpha_context_tokens": 4096,
      "alpha_output_tokens": 128,
      "alpha_concurrency_levels": [
        1,
        4
      ],
      "beta_context_tokens": 16384,
      "beta_output_tokens": 512,
      "beta_concurrency_levels": [
        1,
        4,
        8,
        16
      ],
      "beta_prompt_ids": [
        "short-instruction",
        "code-completion",
        "multi-step-reasoning",
        "long-context-fill"
      ],
      "hardware": {
        "topology": "named certification scenario only: 2-4-stage or 10-plus-stage real multi-machine route",
        "network": "same LAN/WAN class as the existing production route it is compared against",
        "device_class": "generic; not hardcoded to one backend. CPU/CUDA/ROCm/Vulkan/Metal lanes are certified separately per RALPH-CONTEXT.md and only advertised once real-hardware-certified",
        "mtp": "reserved and off for alpha; ownership contract, implementation, and benchmark are required before beta per RALPH-CONTEXT.md"
      },
      "metrics": [
        "ttft_p50_ms",
        "ttft_p95_ms",
        "prefill_tokens_per_sec",
        "decode_tokens_per_sec",
        "aggregate_decode_tokens_per_sec",
        "latency_p50_ms",
        "latency_p95_ms",
        "seam_bytes",
        "seam_latency_ms",
        "queue_wait_ms",
        "peak_rss_bytes",
        "peak_vram_bytes",
        "failures",
        "mtp_enabled"
      ],
      "certification_scenarios": {
        "stage_count": [
          "2-4-stage",
          "10-plus-stage"
        ],
        "quantization": [
          "Q4_K_M",
          "Q8_0",
          "bf16-reference"
        ]
      }
    }
  },
  "gain_attribution": {
    "quantization_model_fit_metrics": [
      "resident_memory_ratio",
      "artifact_size_ratio",
      "exact_match_rate",
      "mean_similarity",
      "peak_rss_bytes",
      "peak_vram_bytes"
    ],
    "runtime_transport_batching_kernel_metrics": [
      "decode_speedup",
      "ttft_ratio",
      "aggregate_throughput_speedup",
      "seam_bytes",
      "seam_latency_ms",
      "queue_wait_ms",
      "prefill_tokens_per_sec"
    ],
    "rule": "A speed or fit claim must cite which axis moved it: a quantization/model-fit change (recipe swap, weight format) or a runtime/transport/batching/kernel change (ShardEngine, gRPC transport, batching, GGML kernel). A distributed-lane win may not be attributed to quantization when the reference recipe already used the same quantization, and a quantization win may not be attributed to distribution or transport."
  },
  "certification_scenarios": {
    "quantization": {
      "names": [
        "Q4_K_M",
        "Q8_0",
        "bf16-reference"
      ],
      "rule": "Named certification-scenario labels only. No product or runtime code path may branch on, default to, or hardcode a specific quantization string; quantization is a dynamic recipe input per RALPH-CONTEXT.md."
    },
    "stage_count": {
      "names": [
        "2-4-stage",
        "10-plus-stage"
      ],
      "rule": "Named certification-scenario labels only, matching DGR-053/DGR-061/DGR-062/DGR-067. No product or runtime code path may hardcode a stage-count range or assume exactly one of these layouts."
    }
  },
  "alpha": {
    "applies_to_lane": "v4-flash-distributed",
    "reference_baseline_lane": "dense-distributed-gguf",
    "correctness": {
      "min_greedy_token_agreement": 0.9,
      "min_mean_state_cosine_similarity": 0.999,
      "forbid_nonfinite_tensors": true,
      "require_fail_closed_on_fingerprint_mismatch": true,
      "require_active_moe_routing": true,
      "require_active_hash_routing_first_three_layers": true,
      "dense_attention_fallback_satisfies_alpha": false
    },
    "useful_speed": {
      "min_decode_speedup_vs_reference_baseline": 1.25,
      "max_ttft_ratio_vs_reference_baseline": 1.25,
      "min_aggregate_throughput_speedup_at_top_concurrency": 1.25,
      "quality_pass_with_speed_fail_verdict": "stop",
      "human_approval": {
        "required": true,
        "approved": false,
        "approved_by": null,
        "approved_at": null,
        "approval_note": "The ratios above are the proposed useful-speed floor, held at the same 25% margin already locked for the whole-model contract (DGR-001/v1, meshnet_node.performance_contract.ContractThresholds). Alpha certification (DGR-054) may not treat useful-speed as satisfied on ratios alone: a human must explicitly approve the observed ratio against real DGR-020/dense/V4 evidence, and this record is the audit trail for that approval."
      }
    },
    "mtp": {
      "reserved": true,
      "enabled_for_alpha": false,
      "ownership_contract_and_benchmark_required_before_beta": true
    },
    "failure_tolerance": {
      "max_failure_rate": 0.0
    },
    "verdicts": [
      "alpha",
      "optimize",
      "stop"
    ],
    "stop_condition": "Stop DeepSeek V4 Flash alpha certification when correctness fails (greedy token agreement, mean state cosine similarity, nonfinite tensors, or fail-closed fingerprint checks), or when useful-speed is not both numerically satisfied and explicitly human-approved against the reference baseline lane under this plan. A quality pass with a speed fail is always 'stop', never 'optimize' — see performance.quality_pass_with_speed_fail_verdict."
  },
  "beta": {
    "applies_to_lane": "v4-flash-distributed",
    "adds": [
      "concurrency",
      "long_context",
      "failure",
      "sustained_throughput"
    ],
    "concurrency": {
      "levels": [
        1,
        4,
        8,
        16
      ],
      "min_aggregate_throughput_speedup_at_max_concurrency": 1.25,
      "max_fairness_deviation": 0.2
    },
    "long_context": {
      "context_tokens": 16384,
      "min_greedy_token_agreement": 0.9,
      "max_ttft_seconds_at_context": 600
    },
    "failure": {
      "consecutive_clean_cold_starts": 2,
      "require_worker_loss_aborts_route": true,
      "require_cache_miss_and_reprefill_on_route_change": true,
      "forbid_silent_kv_migration": true,
      "synthetic_workers_satisfy_beta": false
    },
    "sustained_throughput": {
      "min_duration_minutes": 30,
      "max_throughput_degradation_ratio": 0.1
    },
    "verdicts": [
      "beta",
      "targeted-optimization",
      "stop-rollback"
    ],
    "stop_condition": "Stop or roll back DeepSeek V4 Flash beta when any beta-only threshold fails (concurrency fairness/throughput, long-context correctness or TTFT, failure-recovery semantics, or sustained-throughput degradation), when a required stage-count or quantization certification scenario has no real-hardware evidence, or when MTP evidence is missing given MTP is required before beta per RALPH-CONTEXT.md."
  },
  "amendment_policy": "Thresholds are locked before target execution and may not be weakened, moved, or reinterpreted after results are known. A change requires a new contract_id and contract_version under human review, and the superseded contract is retained. This applies independently of alpha.useful_speed.human_approval, which records sign-off on an observed ratio against these unchanged thresholds, not a change to the thresholds themselves.",
  "contract_sha256": "cb5a482a8f142bf45b1dd401743d408acbfe5f85bab86023144a8c9485ac6379"
}