swactor/specs/mvp_system/run_plan_contract.md

RunPlan Contract

This document defines the behavioral contract for MVP RunPlan formation and projection. It is concerned with externally observable planner behavior: the planner inputs, the emitted RunPlan, derived provisioning messages, and typed rejections.

The planner is the first contract target because the orchestrator is the run authority. Every downstream component receives its stage, layer, edge, and object obligations from the committed plan.

RunPlan Formation

• Given model facts, runtime config, intended node pool, stage count, and placement input, the planner either emits exactly one RunPlan or a typed rejection.
• It never emits a partial plan.
• It never mutates the candidate pool or derives hidden topology outside the plan.

Layer Assignment

• Stage ranges are contiguous.
• Stage ranges do not overlap.
• The union covers the intended GGUF block range.
• Every stage has exactly one non-empty assigned range unless the spec explicitly allows empty ranges.
• Stage indices are 0..stage_count-1.

Edge Assignment

• Every edge id is unique within the run.
• Every edge has exactly one producer and one consumer.
• Token-in edge is orchestrator -> stage 0.
• Activation edge i is stage i -> stage i + 1.
• Token-out edge is stage N-1 -> orchestrator.
• Stages do not derive edge ids from names, hashes, layer ranges, or peers.

Provisioning Projection

• For each StagePlan, deriving ProvisionStage is deterministic.
• A stage receives only its own layer range.
• A stage receives exactly one inbound and one outbound edge provision.
• Outbound provision contains the consumer node_id.
• Inbound provision does not require producer actor address.
• No provision message contains remote actor addresses for data flow.

Object/Ring Spec Consistency

• Every edge has an ObjectSpec and RingSpec.
• Activation max_extent follows the model facts: max_seq_len * hidden_dim * dtype_width_bytes.
• Token edges use token object specs, activation edges use activation object specs.
• Specs are copied consistently into stage provisions.
• Invalid extent, alignment, dtype width, or unsupported shape/layout rejects the plan.

Authority / Rejection

• Unknown node id rejects.
• Duplicate stage assignment rejects.
• Missing stage rejects.
• Invalid stage count rejects.
• Edge endpoint mismatch rejects.
• Model facts inconsistent with requested stage layout reject.
• The planner is the only source of stage, layer, edge, and object-spec assignment.

Test Direction

The tests for this contract should assert guarantees over planner inputs, planner outputs, derived provisioning messages, and typed rejections. They should not assert planner internals, placement heuristics, helper APIs, allocation strategy, or private data structures.

Successful-plan tests should inspect the returned RunPlan and derived ProvisionStage values. Rejection tests should feed contradictory inputs and assert that no plan is emitted.