zacheryasc/swactor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swactor/specs/mvp_system/weight_lifecycle_contract.md
Zachery Aaron Shores-Chmielewski b5de4c9bd6 docs(mvp): lay out mvp-system spec and contracts 
Add MVP_SYSTEM_SPEC plus per-component contract docs (arena manager, device bridge,
gpu worker ctl/ingress/egress/process-adapter, orchestrator run-fsm/token-endpoint,
run plan, stage controller, tx_rx edge, weights). Scaffold the guarantee tests against
the (empty) mvp-system crate.


Signed-off-by: Zachery Aaron Shores-Chmielewski <zacheryasc@gmail.com>
2026-06-23 11:12:45 +04:00

1.6 KiB
Raw Blame History

Weight Lifecycle Contract

This document defines the behavioral contract for stage-local weight work. Weights are persistent run state for a stage and must be usable before the stage reports StageReady.

Assignment

  • The stage receives its weight source from ProvisionStage.
  • The stage receives exactly one assigned layer range.
  • The stage validates the assigned layer range against the run plan.
  • The stage does not load layers outside its assigned range as graph-visible ownership.

Loading

  • A stage may download a whole GGUF and load only its range.
  • A stage may download physical shards containing its range.
  • A stage may use a cached artifact that already exists on the node.
  • The physical loading mechanism is implementation-defined.
  • The system-visible outcome is WeightsReady or StageFault.

WeightsReady

  • WeightsReady requires assigned artifact bytes to be locally available or cached.
  • WeightsReady requires the assigned layer range to be validated.
  • WeightsReady requires the worker to have loaded or bound the range needed for execution.
  • WeightsReady happens before StageReady.

Failure Behavior

  • Download failure faults the stage.
  • Parse failure faults the stage.
  • Device allocation failure faults the stage.
  • Binding failure faults the stage.
  • Invalid layer range faults the stage.

Test Direction

Tests should treat weight loading as a stage-local black box with observable events. Successful tests should assert WeightsReady before StageReady. Failure tests should inject download, parse, allocation, and bind failures and assert StageFault with no StageReady.