zacheryasc/swactor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
swactor/specs/mvp_system/device_bridge_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.9 KiB
Raw Blame History

Device Bridge Contract

This document defines the behavioral contract for the backend-specific device bridge used by the GPU worker. The bridge is the worker's boundary between host ring memory, device memory, and tinygrad-compatible views.

Allocation

  • alloc_device(ObjectSpec, extent) creates a device allocation suitable for the object spec and extent.
  • Allocation failure is reported as device allocation failure.
  • Allocations are tied to the current worker generation.
  • free_device releases an allocation after no compute or copy event depends on it.

Host To Device

  • host_to_device copies exactly the requested host range to the requested device range.
  • For synchronous copies, return means bytes are safe to release.
  • For asynchronous copies, completion of the copy event means bytes are safe to release.
  • Copy failure is reported as device copy failure.

Device To Host

  • device_to_host copies exactly the requested device range to the requested host range.
  • For synchronous copies, return means host bytes are valid.
  • For asynchronous copies, completion of the copy event means host bytes are valid.
  • Copy failure is reported as output copy failure or device copy failure.

Tinygrad View

  • wrap_for_tinygrad creates a tinygrad-compatible view over a device allocation.
  • The view matches the tensor view spec used by the role.
  • Invalid view shape or dtype fails the step.

Lifetime

  • Device allocations are not freed while compute uses them.
  • Device allocations are not freed while copy events use them.
  • Worker restart invalidates all prior device handles.
  • Old-generation handles are rejected.

Test Direction

Tests should use a fake backend to observe allocation, copy, completion, view, and free calls. Success tests should assert exact ranges and safe cursor-release points. Fault tests should inject allocation failure, copy failure, invalid view, and old-generation handles.