swactor/specs/mvp_system/weight_lifecycle_contract.md

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.