swactor/DATA_PLANE_PATH_API_HANDOFF.md

Data-plane path API handoff

Purpose

Pause-point for the first Myelin GPU job flow. We proved the current end-to-end path, then identified that its temporary Python/data-plane boundary is the wrong long-term abstraction.

Resume by working backward from the approved namespace/path API and designing fundamental path resolution before changing the binding again.

What was accomplished

Working manual GPU flow

The repository now has a manually exercised path through:

1. Myelin orchestrator startup.
2. Local Docker GPU-node provisioning from the Provision panel.
3. Runtime-image selection during provisioning.
4. Fleet-panel GPU-job submission.
5. Model-weight transfer over the data-plane edge transport.
6. Tinygrad CUDA inference in the worker job image.
7. Result transfer back to the orchestrator and bare Fleet display.

The observed deterministic result was:

CUDA -> [2.75, -8.75]

The flow was repeated after worker teardown/reprovisioning and produced the same result.

Runtime and deterministic fixture

• apps/myelin/node-image/Dockerfile.job-tinygrad builds the small Tinygrad CUDA job image.
• The selected image is carried through the existing provisioning request/spec and shown by the existing UI.
• apps/myelin/jobs/tiny_linear.weights is a 24-byte, six-f32 fixture:

matrix = [[1.5, -2.0],
          [0.5,  4.0]]
bias   = [0.25, -0.75]
input  = [2.0, -1.0]
output = [2.75, -8.75]

• apps/myelin/jobs/tiny_linear_inference.py performs GPU-only inference and rejects non-CUDA Tinygrad selection.

Job/data-plane integration

The current implementation connects job-runner lifecycle to real Iroh edge streams and the Myelin Fleet probe. Work completed during this pass included:

• model ingress and result egress over EDGE_ALPN rather than actor-message payloads;
• reverse-route assignment acknowledgement so a fast job-exit event is not lost;
• edge-stream completion acknowledgement before sender teardown;
• explicit stream-fault propagation into Fleet job failure;
• result framing/parsing and deterministic Fleet result display;
• job-runner assignment/lifecycle coverage for the acknowledgement ordering.

Verification already performed

At the completed checkpoint:

• swactor-job-runner: 12 focused tests passed;
• iroh-driver: 14 tests passed;
• Python binding built successfully with stable-ABI forward compatibility enabled for the workstation Python version;
• Myelin test targets compiled;
• final Docker node and Tinygrad job images built;
• the UI-driven local Docker GPU scenario returned [2.75, -8.75];
• temporary worker containers, orchestrators, state directories, and debug sessions were removed; built images were intentionally retained.

The approved Python API direction

Python names the data it wants. Swactor does not declare application ports or application data types.

async def main(ctx: swactor.Context) -> None:
    weights = await ctx.data.read_blob(
        "/models/tiny-linear/weights",
    )

    async with ctx.data.write_stream(
        "/runs/self/results/inference",
    ) as results:
        await results.write(b"opaque application bytes")


swactor.run(main)

The intended binding primitives are:

ctx.data.read_blob(path)       # finite immutable bytes
ctx.data.write_blob(path)      # finite output
ctx.data.read_stream(path)     # incrementally readable bytes
ctx.data.write_stream(path)    # incrementally writable bytes

Public concepts should remain limited to:

Context
DataPlane
Blob
ArenaView
StreamReader
StreamWriter

Boundary

Swactor may understand:

• logical names and paths;
• blob versus stream;
• byte length and optional content digest;
• stream ordering and termination;
• arena leases, alignment, generations, cursors, and backpressure;
• authorization, placement, routing, and lifecycle.

Swactor must not understand:

• tensors;
• dtypes or shapes;
• byte order as application schema;
• JSON or JSON schemas;
• model formats;
• inference-result semantics.

Therefore there should be no swactor.Tensor, swactor.Json, typed job-port manifest, or orchestrator-provided application port declaration.

Application code interprets bytes. For the fixed model:

weights_blob = await ctx.data.read_blob("/models/tiny-linear/weights")

expected_bytes = struct.calcsize("<6f")
if weights_blob.length != expected_bytes:
    raise ValueError(
        f"expected {expected_bytes} model bytes, "
        f"received {weights_blob.length}"
    )

with weights_blob.map() as mapped:
    weights = struct.unpack_from("<6f", mapped)

Tinygrad owns tensor construction and the host-to-GPU upload. JSON encoding of results likewise remains Python logic:

encoded = json.dumps(
    {"device": device, "output": output},
    separators=(",", ":"),
    sort_keys=True,
).encode("utf-8")

async with ctx.data.write_stream(
    "/runs/self/results/inference"
) as results:
    await results.write(encoded)

A stream is opaque ordered bytes. If the application wants records, JSON Lines, protobuf, or another framing scheme, the application supplies it.

Shared-memory direction

Unix sockets are rejected for the Python/data-plane boundary.

The data-plane already has the correct foundation:

• ArenaManager::arena_fd() exposes Linux shared backing;
• arena leases are offset-based rather than process-pointer-based;
• ring identity, generation, reservation, commit, consume, and wake contracts already exist;
• EdgeRuntime already composes network edges, arena leases, and worker loading.

The intended local flow is:

remote edge -> ingress arena ring -> Python mapped view
Python bytes -> egress arena ring -> remote edge

Python should inherit and map the arena backing. Async operations wait on shared ring state plus a notification primitive; payloads remain in shared memory.

Current implementation gaps

These are implementation gaps, not reasons to add another transport:

• ArenaBacking exposes read_at/write_at, but the binding does not yet expose an mmap view.
• RingHelperHarness still uses a process-local Vec<u8>; production ring headers and atomic cursors must live in arena memory.
• LayoutPointer::NoProcessPointer is not yet resolved into a mapped process-local view.
• Python process bootstrap does not yet receive the arena and wake descriptors plus its initial control-ring layouts.
• The Python binding currently contains Tokio UnixStream input/output classes. They are temporary and should be removed.
• EmbeddedJobDataPlane currently bridges through local Unix sockets. That is also temporary.
• The Tinygrad test bridge currently reads arena data as a file and uses line-delimited JSON control. The final binding should map the arena directly.
• The first honest GPU path will have one arena-to-CUDA upload performed by Tinygrad. Direct device-handle integration is separate from path resolution and is not required to design the namespace API.

Bootstrap slice (implemented)

The first unknown down the approved API chain — what swactor.run(main) consumes before main(ctx) can exist — is now implemented and tested.

Contract:

• The host execs the job process with two inherited descriptors named by SWACTOR_ARENA_FD and SWACTOR_WAKE_FD; nothing else crosses the boundary at spawn.
• Arena offset 0 holds a fixed 48-byte little-endian bootstrap header (SWBS magic, version, reserved-zero fields, arena size, control-ring offset/capacity/generation). Canonical definition: crates/data-plane/src/bootstrap.rs — header layout, shared parser, write_bootstrap host writer (header region and control ring are disjoint leases under the arena's own placement law; all writes complete before the handoff is returned).
• The binding's run() maps the arena read-only, takes ground truth from fstat (never the header's size claim), validates via the shared parser, arms FD_CLOEXEC on the wake descriptor, closes the arena descriptor after mapping, builds Context/DataPlane, and drives main on asyncio. Fail-fast: any defect raises swactor.BootstrapError (swactor.SwactorError subclass) before main is invoked.

Removed with this slice: the binding's Tokio UnixStream DataPlaneInput/DataPlaneOutput classes and the SWACTOR_DATA_PLANE_INPUT/OUTPUT environment variables.

Verification (all passing):

• data-plane: 12 bootstrap guarantee tests (parser defect table, fuzzed pages, writer round-trip, ring zero/stamp, env ABI, fd shape).
• Python binding: 29 tests (crates/bindings/python/tests/) covering the defect table in-process and across real exec boundaries, wake opacity, CLOEXEC grandchild isolation, exit-code contract, and surface leakage.
• iroh-driver, myelin, swactor-job-runner still compile; all pre-existing suites pass.

Deliberately unchanged: EmbeddedJobDataPlane still bridges weights/results over local Unix sockets, and its configure() still emits the legacy socket environment — the binding no longer reads it. That bridge is replaced when the arena carries real path data (next slice: control-ring framing for read_blob), so the proven GPU scenario is not left half-cut-over.

Where design resumes: fundamental path resolution

The next work starts with path semantics and resolution, not binding implementation.

Two layers must remain distinct:

logical path
    -> blob owner or matched stream participants
    -> actor addresses
    -> current nodes
    -> live transport route
    -> provisioned edge and arena rings

The candidate direction discussed, but not yet finalized, is:

1. A data-directory authority resolves canonical paths.
2. Blob paths resolve to a current owner and pinned generation.
3. Stream paths rendezvous one egress participant with one ingress participant for v1.
4. Existing swactor actor-directory state resolves participant actors to their current nodes.
5. The Iroh driver resolves nodes to live direct/relay transport routes.
6. Edge provisioning allocates an EdgeId, installs ingress/egress arena rings, and only then opens the byte stream.
7. Python sees none of the actor, node, endpoint, edge, or ring identities.

The concrete scenario to use while settling the design:

/models/tiny-linear/weights
    blob read by the worker job

/runs/self/results/inference
    live stream written by the worker job
    `self` scoped to the current run

Questions to settle first when work resumes:

• Path grammar, normalization, and scoped aliases such as self.
• Who owns the root namespace and whether authority delegates by prefix.
• How a blob publisher binds, updates, and tombstones a path generation.
• How stream readers and writers register, wait, match, cancel, and close.
• How path capabilities are attached to the job context and enforced.
• Which actor owns edge-plan creation and the ordering between ring installation and transport connection.
• Failure behavior when a path is absent, an owner moves, a participant exits, or a generation changes during resolution.

Do not redesign the UI, job specification, model format, or inference logic while resolving these fundamentals. Work backward from the approved Python API and preserve the already-proven manual GPU scenario as the integration target.

Explicitly rejected directions

• Orchestration declaring named application ports for Python.
• Static job-port manifests.
• Actor IDs, edge IDs, peers, or socket paths exposed to Python.
• Per-port Unix sockets or a separate local control socket.
• Swactor-owned tensor, JSON, model, or inference schemas.
• Embedding application semantics into the data-plane.