Goldy Runtime Mapping

Status: Implementation note for Goldy 0.3.x. Claims use the labels in Terminology.

How Goldy realizes the Fondaco machine from Machine Specification. Goldy is a runtime, not the machine. Where this chapter disagrees with the spec, the spec governs.

Hardware terms (GPU, Vulkan, Metal, DX12, shader, fence) appear because Goldy must speak them. They have no normative meaning in the Fondaco machine.

For why Goldy looks this way, see Design Thesis. For day-to-day usage, start at the Introduction.

1. Goldy realizes a Fondaco machine

Shipped. Goldy is a Rust library that admits dispatches, honors scheme partial orders, maintains parcel identity across physical activity, and acts at gates as the machine requires.

It targets 2020-era heterogeneous compute: a host processor plus one or more GPUs via Vulkan 1.4+, DX12, or native Metal (macOS).

The spec's runtime is a single agent. Goldy exposes that agent as a cloneable Runtime: warehouse owner for retained parcels, shader and pipeline factory, capabilities, and diagnostics. Context is a submission timeline (transient/deposit pools, scheme recording). Backend device handles stay private.

Goldy still splits execution across:

• Host (Rust): parcel identity, schemes, ledger analysis, gates, exchanges
• GPU queue: executes admitted dispatches

That split is a substrate artifact, not a machine requirement.

2. Status overview

3. Dispatches

Shipped. A Goldy dispatch is a compute or graphics submission to the accelerator.

• Script: Slang compiled through virtual_main to SPIR-V, DXIL, or Metal IR. Goldy fixes Slang; the machine does not require it. See Virtual Entry Points.
• Execution: Workgroup grid (threadgroups on Metal). dispatch_indirect where the backend allows.
• Claims: NodeAccess on scheme nodes — read, write, read-write — mapped to public / private / private-inaugural ownership.

Non-computing dispatches also Shipped: buffer copy, buffer write, texture upload, buffer clear, present / copy-to-swapchain.

Raster: fused dispatches, not machine-opaque scripts

Shipped. A Goldy render-pass node is one dispatch covering a framebuffer epoch (vkCmdBeginRendering … EndRendering, Metal render encoder, DX12 render pass / RTV span) plus every draw / dispatch_mesh recorded in that epoch.

In the machine, each of those draws may be a dispatch. Goldy fuses them at record time because the 2026 portable ABIs do not expose a gate between draws without checking the attachment back in.

CPU dispatches (Shipped, 0.2.x): Scheme::cpu_node admits a serial host function whose parameter list is the virtual main (&[T] / &mut [T] per bound parcel, then scalars). The machine does not distinguish where a dispatch executes; Goldy realizes host execution by staging bound parcels through readback/upload copies around a fence wait, so the node is a full drain of the device pipeline. See CPU Dispatches.

Goldy does not preserve shader invocation identity across dispatch gates; logical threads must persist state in parcels.

4. Parcels and bindless internals

Shipped. A Goldy parcel is a stable handle. Programs never author raw (category, index) bindless slots.

Bindless descriptor indexing is backend-internal:

• Rust: Public types are Parcel, Buffer, Texture, Scheme, exchanges. Bindless resolution happens at scheme record / submit.
• Slang: Typed parameters (Scattered<T>, BufRO<T>, …). virtual_main generates slot packing.

Program-visible are access-pattern categories (Layer B): Scattered, BufRO, Broadcast, Interpolated, DirectSpatial, Filter. See Parcels and Design Thesis.

Parcel identity and reslot

Shipped. Identity is the handle, not the descriptor slot. Handles stay stable across physical growth (Buffer::resize_to), transient aliasing within an epoch, and backend pool rotation.

When backing changes (reslot), Goldy:

1. Keeps the handle unchanged
2. Gives the new allocation a new descriptor slot; old slots remain valid until in-flight work retires
3. Invalidates retained command buffers that embedded stale slots

This follows DX12 / Vulkan / Metal descriptor versioning. See Buffers and VRAM Allocator.

5. Warehouse and memory

Shipped (partial). Physical medium is managed by Runtime (retained warehouse), VramAllocator, and TransientPool. See Runtime-Owned Memory and Transient Allocation.

Goldy distinguishes three quantities:

Budget enforcement keys on committed. Resident enters reactively via OS memory-pressure signals.

Shipped residency models per backend: ManagedAllocation (discrete Vulkan / DX12), PageOnFault (Apple Metal), plus capability queries for resize cost (Constant, PageBind, Copy).

Designed: defragmentation, proactive memory-pressure petition delivery at gates.

6. Exchanges

Shipped. Primary exchange: surface presentation.

#![allow(unused)]
fn main() {
let transaction = surface_exchange.bind_render_target(&mut scheme, &scene_rt)?;
let mut submission = scheme.submit()?;
(&mut submission >> &transaction).take()?; // present
}

• Binding does not acquire a drawable; acquire runs at submit when the partition needs it
• (&mut submission >> &transaction).take() is sugar for transaction.claim(&mut submission)?.consume(); the &mut borrow leaves other claims untouched
• Claim::consume / Claim::discard remain the canonical settlement verbs
• The program never passes raw GPU addresses to the compositor

Shipped CPU readback: host claims via (&mut submission >> &parcel).take::<T>() (PendingHostRead / HostView). See Settlement and Compute to Surface.

Shipped CPU upload: MemoryExchange::bind_deposit records copy topology once. (&deposit << &data)? (or DepositTransaction::write) prepares an occurrence for this submission; Scheme::submit claims it internally and graph execution consumes the claim at the deposit copy dispatch. Staging backings are exchange-owned and never enter the parcel ledger. Retirement is an exchange-local epoch, distinct from destination RAW/WAR tracking.

Designed: video-encoder exchange (foreign read continues after enqueue).

7. Schemes and GraphIR

Shipped. Public type: Scheme. Internally Goldy holds GraphIR — nodes, ownership-derived edges, group provenance, wave / partition analysis, retention fingerprints.

Scheme::include copies a child's description into the parent as one group (snapshot: later mutation of the child does not affect the parent; the child stays independently submittable). Scheme::group is sugar: a temporary child on the same Context, then include. Group-level .after(prior) expands to node-pair precedences when the schedule cache is rebuilt — never on the clean submit path.

Restrictions (all GoldyError::Validation at include time; the parent is left untouched): same Context; no pending record errors; no CPU dispatch, deposit, present/swapchain, yielding, or transient nodes; all child stamps alive (StaleResource otherwise).

On Scheme::submit:

• Dependency analysis inserts barriers
• Transient regions are colored for aliasing
• Partitions may acquire exchange backing
• Retained command buffers replay when bindings are unchanged

Designed scheme transformations (spec §8): fusion (mega-kernel), splitting at yield points (wavefront), dead-dispatch elision beyond basic analysis.

Goldy refuses ill-formed schemes (conflicting unordered private claims) rather than producing unspecified results — a deliberate narrowing of spec latitude.

8. Gates and ordering

Shipped. A gate is the interval between Scheme::submit calls and retirement via Context::boundary_crossed(T).

At a gate Goldy may reclaim deferred allocations, flush VRAM deferred rings, and service timeline signals.

Shipped cross-submission ordering: the runtime enforces ledger precedences across schemes on the same Context, using GPU barriers or host waits as needed. Clients must not assume which lever is used.

Pipeline depth (in-flight submissions) is client pacing — surface depth, FrameOrchestrator, when to consume claims. See Pipelined Frames.

9. Scripts: non-yielding today

Shipped. Public shaders today are non-yielding: [goldy_compute], [goldy_vertex], [goldy_fragment].

Designed yielding scripts:

• $yield intrinsic in the virtual-entry-point transform
• Script-state preservation (register spin-wait, workgroup-local, or parcel-backed)
• Yield-point petitions (limited runtime power, not full gate powers)

10. Calling conventions

Shipped:

• Slang as sole script language — Slang in One Source
• Virtual entry points — typed parameters; virtual_main generates platform wrappers
• Push-constant layout — bindless indices + scalars prepended per dispatch (backend-internal)
• Access categories — validated at scheme record time

Designed: $yield petition descriptors, promise / continuation bindless category, paged-parcel fault servicing.

Portable programs depend on typed access categories and scheme structure, not on bindless heap layout.

11. Where Goldy constrains the spec

Deliberate restrictions for modern desktop / laptop workloads:

• Refuses ill-formed schemes
• Fixed Slang scripts
• Closed typed-access category set
• Workgroup-grid execution model
• Single accelerator queue per device (heterogeneous multi-queue: Designed)
• 2020+ hardware floor (Vulkan 1.4+, DX12 Enhanced Barriers, Metal Tier 2+)
• Raster grain: one scheme node per framebuffer epoch (per-draw dispatches: Designed)

For older hardware or maximum portability, use wgpu. See Goldy vs wgpu and Target Hardware.

12. Abstract the medium, expose cost

Normative for Goldy design.

• Layer A (medium): VRAM, residency, relocation, descriptor slots — abstracted; runtime-owned
• Layer B (cost): Registers, occupancy, coalescing, access patterns, first-touch latency — exposed and queryable

Goldy must not present Layer A operations as uniform-cost or hide them entirely. Access-pattern types (Scattered vs Broadcast vs Interpolated) exist because hardware treats them differently.

Capability queries report backend, residency model, resize cost, zero-copy readback, and optional features honestly.

Appendix: Fondaco ↔ Goldy

Analogues are not equivalences. A scheme is the program's computation, not merely a scheduling artifact. An exchange preserves program sovereignty over parcels; a raw swapchain handle does not.

Full vocabulary: Terminology.