Goldy Runtime Mapping

Status: Implementation note for Goldy 0.2.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 splits it into:

• Host (Rust): parcel identity, schemes, ledger analysis, gates, exchanges
• Device (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.

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 VramAllocator, RetainedPool, and TransientPool. See RetainedPool and Parcel 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()?;
let claim = transaction.claim(&mut submission)?;
claim.consume()?; // present
}

• Binding does not acquire a drawable; acquire runs at submit when the partition needs it
• Claim::consume is terminal
• The program never passes raw GPU addresses to the compositor

Shipped CPU readback: MemoryExchange with WithdrawTransaction / WithdrawClaim. See Settlement and Compute to Surface.

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, wave / partition analysis, retention fingerprints.

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+)

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.