zacheryasc/swactor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swactor/specs/mvp_system/edge_establisher_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

2.3 KiB
Raw Blame History

EdgeEstablisher Contract

This document defines the behavioral contract for local edge establishment. It turns ProvisionTx or ProvisionRx into a local edge actor, arena lease, worker ring installation, driver establishment, and ready/fault outcome.

Provisioning

  • Each node has one EdgeEstablisher.
  • ProvisionTx creates a local send edge record.
  • ProvisionRx creates a local receive edge record.
  • The producer needs the consumer node_id.
  • The consumer needs the shared edge_id.
  • Remote actor addresses are not required for data flow.

Lease Flow

  • Establishment requests one arena lease per edge end.
  • RingLeased matching the request advances the edge record.
  • RingLeaseRejected matching the request fails the edge record.
  • Stale lease events for stopped records do not install worker or pump state.
  • An unused fresh lease granted after cancellation is released.

Worker Ring Installation

  • The edge establishes driver state only after worker or token endpoint ring installation succeeds.
  • RingInstalled matching the edge advances establishment.
  • RingFault before readiness stops establishment.
  • Ring installation uses the ObjectSpec and RingSpec from provisioning.

Driver Establishment

  • Send edges call EstablishSend with edge_id, consumer node_id, and local ring layout.
  • Receive edges call EstablishRecv with edge_id and local ring layout.
  • DriverEdgeReady marks the local edge actor ready.
  • Stream and pump behavior are driver-owned after readiness.

Ready And Hot Path

  • Ready means local actor, arena lease, worker/token ring, and driver state are installed.
  • The hot path runs without EdgeEstablisher.
  • The establisher observes coarse ready, stopped, and fault events only.

Stopping

  • StopEdge cancels queued leases.
  • StopEdge stops pumps if present.
  • StopEdge uninstalls worker rings if installed.
  • The arena lease is released only after quiescence proof.
  • Stopped is terminal for that edge record.

Test Direction

Tests should drive the public establishment FSM with lease, worker, driver, and stop events. Successful tests should assert the order lease -> install -> driver -> ready. Fault tests should inject lease rejection, ring fault, driver fault, stale events, and stop races and assert no hot-path state survives incorrectly.