Resource kinds

A grafOS resource is any handle the fabric can lease, scope to a tenant, and tear down on expiry. Today there are five resource kinds. They share lease lifecycle and capability-token bindings; they differ in the data plane underneath.

Mem — fabric memory

Pooled / fabric-attached memory. Today: RDMA-backed arenas. Tomorrow: CXL-attached pools.

Lease grants access to a typed region of memory, addressable as a byte range. The data plane is RDMA QPs (or whatever the underlying fabric provides). The SDK gives you typed wrappers:

• grafos-std::FabricBuffer — raw byte-addressable region.
• grafos-collections::FabricVec — Vec<T> semantics across leased memory; multiple writers visible if they hold leases on the same region.
• grafos-collections::FabricHashMap — like above but a hash map. Hot tier of grafos-kv.
• grafos-tensor — tensor view over FabricBuffer, for math on leased GPU memory.

The fabric guarantees:

• Lease-bound: reads/writes after expiry fail closed.
• Bounded by quota: tenant-level memory quota enforced at admission (you’ll see lease_denied: quota if you exceed).
• Generation-tracked: each lease has a generation; stale references fail with a typed error.

What it does NOT guarantee:

• Cross-region atomicity. Use grafos-sync atomics for ordering between concurrent writers.
• Persistence. Memory is volatile — if the cell holding the region restarts, the region is gone. Use Block for persistence.

Block — fabric block storage

Fabric-attached block devices. Today: NVMe-oF (loop-backed in dev/CI, real NVMe targets in production cells).

Lease grants access to a block range on a target device. Typical access patterns:

• grafos-store::BlockObjectStore — object-storage-style API on top of a leased block device, with CRC32 verification.
• grafos-fs — distributed filesystem on leased block storage.
• grafos-collections::Durable<T> — single-object durable container that survives cell restarts.

The fabric guarantees:

• Lease-bound. Block ops after expiry fail closed.
• Atomic-block writes. The underlying device’s atomicity (typically 512B or 4KB sector) is preserved.
• Survives cell restart. Data persists across the lifetime of the underlying device.

It does NOT guarantee:

• Filesystem semantics by default. grafos-fs adds those on top.
• Cross-block atomicity. Use the higher-level grafos-store or roll your own with grafos-sync for the metadata.

Net — leased network interfaces

Leased per-tenant network interfaces, scoped to a flow-rule installed on the fabric NIC. Today: traditional NIC + flow-table; future: smartNIC offloads.

The lease binds a tenant to a network interface configuration: source IPs, source ports, destination filters. Sockets and listeners on top:

• grafos-net::Listener — bind to a leased interface, accept connections from peers permitted by the flow rule.
• grafos-net::Socket — outbound connection through a leased interface.
• DNS via the leased interface’s resolver.

The fabric guarantees:

• Lease-bound. New connections after expiry fail closed; in-flight connections RST.
• Tenant isolation. Other tenants’ flow rules don’t intercept your traffic.

It does NOT guarantee:

• TLS by default. Bring your own TLS termination (or use higher-level RPC primitives that do).
• Bandwidth caps without an explicit quota in the lease. Quota is in the spec but may not be enforced on every cell.

GPU — leased GPU contexts

Leased GPU contexts for accelerator workloads. Today: NVIDIA via fabricBIOS-GPU bindings; other vendors planned.

Lease grants either a whole-GPU exclusive context or a fractional context (sliced by SM count or memory). The data plane is GPU-vendor-specific (NVIDIA: CUDA contexts via the fabricBIOS gpu-protocol crate).

• grafos-tensor — typed tensor ops on leased GPU memory.
• grafos-std GPU primitives — submit kernels, allocate device memory, transfer.

The fabric guarantees:

• Lease-bound. GPU submissions after expiry fail closed; in-flight kernels are torn down at the GPU driver level.
• Exclusivity contract. If you ask for WholeCard and get it, no other tenant lands on the same physical GPU for the lifetime of your lease. See /spec/gpu-exclusivity-wire-format for the wire format.
• Fenced on teardown failure. If the GPU driver can’t cleanly tear down (driver hang, runaway kernel), the GPU transitions to FENCED. No new leases on that GPU until it’s observably reset (typically a host reboot).

CPU — leased CPU sets

Leased CPU sets for workloads that need coordinated affinity (e.g. real-time pipelines, dedicated cores).

Lease grants a set of physical or logical cores on a specific cell, optionally with isolation properties (StrictIsolated — no SMT siblings shared with other tenants, no neighbor on the same L3 cache, etc.).

• grafos-std::CpuBuilder — request a CPU set with isolation requirements.
• grafos-jobs — burst compute scaffolding on leased CPU sets.

See /spec/cpu-isolation-wire-format and /spec/bare-metal-cpu-lease-semantics for the formal isolation guarantees.

Resource graph: connecting the kinds

A real program usually leases more than one kind: a Net interface to receive requests, a Mem region for working state, a Block range for durable output, a GPU for inference. The grafOS resource graph (typed Nodes connected by Ports and Edges; see grafos-core) is how programs declare those connections explicitly. The scheduler reads the graph to place tasklets.

You don’t usually write graph code by hand — the SDK builds it for you. But it’s there, observable, and rewritable; the grafos-runtime crate exposes the runtime engine.

Where to next

• Capability tokens — how leases on these resources become tokens you carry into data-plane ops.
• The wire formats for kind-specific operations are in /spec/ — gpu-exclusivity-wire-format.md, cpu-isolation-wire-format.md, etc.
• The SDK rustdoc at grafos-std is the authoritative type/method reference.