3dJan · 3dJan · Apr 27, 2026 · Apr 27, 2026 · May 4, 2026 · May 13, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,4 +1,4 @@
-
+No explanations, just the code.
 
 # C++ Coding Guidelines
 
@@ -87,4 +87,47 @@
 - **FIXME**: Use `// FIXME: description` for known issues that need fixing.
 - **Documentatioon**: Only add comments that add additional value. Avoid stating the obvious.
 
-By following these guidelines, you can ensure clean, efficient, and maintainable C++ code.
+By following these guidelines, you can ensure clean, efficient, and maintainable C++ code.
+
+<!-- headroom:rtk-instructions -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+When running shell commands, **always prefix with `rtk`**. This reduces context
+usage by 60-90% with zero behavior change. If rtk has no filter for a command,
+it passes through unchanged — so it is always safe to use.
+
+## Key Commands
+```bash
+# Git (59-80% savings)
+rtk git status          rtk git diff            rtk git log
+
+# Files & Search (60-75% savings)
+rtk ls <path>           rtk read <file>         rtk grep <pattern>
+rtk find <pattern>      rtk diff <file>
+
+# Test (90-99% savings) — shows failures only
+rtk pytest tests/       rtk cargo test          rtk test <cmd>
+
+# Build & Lint (80-90% savings) — shows errors only
+rtk tsc                 rtk lint                rtk cargo build
+rtk prettier --check    rtk mypy                rtk ruff check
+
+# Analysis (70-90% savings)
+rtk err <cmd>           rtk log <file>          rtk json <file>
+rtk summary <cmd>       rtk deps                rtk env
+
+# GitHub (26-87% savings)
+rtk gh pr view <n>      rtk gh run list         rtk gh issue list
+
+# Infrastructure (85% savings)
+rtk docker ps           rtk kubectl get         rtk docker logs <c>
+
+# Package managers (70-90% savings)
+rtk pip list            rtk pnpm install        rtk npm run <script>
+```
+
+## Rules
+- In command chains, prefix each segment: `rtk git add . && rtk git commit -m "msg"`
+- For debugging, use raw command without rtk prefix
+- `rtk proxy <cmd>` runs command without filtering but tracks usage
+<!-- /headroom:rtk-instructions -->
diff --git a/.serena/memories/library-best-practices.md b/.serena/memories/library-best-practices.md
@@ -0,0 +1,49 @@
+# 3MF Library Best Practices
+
+## What Makes a Good Library Item?
+
+### Required Metadata
+- **Name**: lower_snake_case, descriptive, no spaces or special chars except hyphens/underscores
+- **Description**: One sentence explaining what the item does and key parameters
+- **Tags**: Minimum 5 relevant keywords for discoverability (e.g., "primitive", "cone", "taper", "basic")
+- **Tagged Function**: Exactly one function marked as tagged. Return type depends on purpose:
+  - `float shape` for SDF primitives/modifiers
+  - `vec3 result` for position transformations (symmetry, rotation, etc.)
+  - `vec3 color` for textures/materials
+
+### Code Quality
+- Clean bounding box suitable for thumbnail rendering
+- Well-named parameters with meaningful defaults where appropriate
+- A `main` function demonstrating typical usage
+- No duplicate function definitions (each name should have unique ID)
+- Proper dependency ordering in program snippet
+
+### Visual Appeal (for Thumbnails)
+- Geometry fills 70-85% of thumbnail frame
+- Isometric camera angle showing 3D form clearly
+- Consistent lighting: directional light from upper-left, ambient fill
+- Neutral background (light gray or white)
+- Characteristic features visible at thumbnail size (256x256 minimum)
+
+## Anti-Patterns to Avoid
+- Empty entries (no description/tags/tagged functions)
+- Missing tags on any entry
+- Duplicate function names within same file
+- Nearly duplicate entries (e.g., unionWithColor vs union_with_color)
+
+## Naming Conventions
+- Primitives: `sphere`, `cylinder`, `cone`, etc.
+- Modifiers: `round`, `shell`, `offset` (verb-based)
+- Operations: `polar_repetition`, `symmetryX` (noun-based with parameter suffix)
+- Mechanical: `helix_spring`, `involute_gear` (compound nouns)
+
+## Category Structure
+```
+primitives/     - Basic SDF shapes (sphere, cylinder, cone, etc.)
+csg/           - Boolean operations (union, intersection, subtraction)
+modifiers/     - Shape deformations (round, shell, offset)
+operations/    - Domain transformations (symmetryX, polar_repetition)
+lattices/      - Periodic structures (gyroid, honeycomb)
+mechanical/    - Engineering parts (gear, spring, thread)
+textures/      - Procedural textures (WoodTexture)
+```
diff --git a/docs/architecture/gpu_access_coordination.md b/docs/architecture/gpu_access_coordination.md
@@ -0,0 +1,53 @@
+# GPU Access Coordination
+
+Gladius uses multiple OpenCL command queues: one lazily-created queue per calling thread plus explicit worker queues for async rendering. OpenCL queues do not implicitly synchronize with each other, so shared buffers/images must be ordered explicitly.
+
+## Core invariant
+
+Every shared OpenCL memory-object access across queues must be ordered by one of:
+
+1. an event wait list produced by `GpuAccessCoordinator`, or
+2. an explicit host wait that is reported back to the coordinator.
+
+Host-side mutexes are not sufficient unless they are held until the GPU command using the protected resource has completed.
+
+## Main types
+
+- `GpuAccessCoordinator` is the pure, GPU-free state model. It tracks resource IDs, generations, read/write leases, fake/production event IDs, stale generations, and deferred retirement.
+- `OpenClEventRegistry` maps coordinator event IDs to `cl::Event` objects and polls or waits for completion.
+- `GpuKernelAccessGuard` is the production RAII bridge. It begins one or more resource accesses, converts dependency IDs to OpenCL wait lists, and records the returned kernel event when the enqueue succeeds.
+- `RenderPayloadSnapshot` captures the generation handles for the common render payload: primitive metadata, primitive data, precomputed SDF, parameter buffer, and command buffer.
+
+## Published generations
+
+Each `Buffer<T>` and `ImageImpl<T>` owns a stable coordinator resource ID and a current generation. Host writes, buffer reallocations, image reallocations, and clears retire the previous generation before mutating or releasing the backing OpenCL object.
+
+A kernel launch should use the generation handles captured at launch time. If a later host write advances a generation, stale snapshots can be rejected instead of silently reading mixed old/new state.
+
+## Conservative first-slice policy
+
+The first implementation is whole-resource based:
+
+- reads can overlap with reads;
+- writes wait for previous readers and writers;
+- reads wait for the previous writer;
+- `Primitives::data` is tracked as one conservative resource even though it contains several logical regions;
+- old generations are not released until known events have completed.
+
+This is intentionally safer than region-level aliasing. Region-level optimization can be added later once workflow tests prove the invariants.
+
+The current production rollout also prefers conservative generation retirement over immediate physical double-buffering. Host writes and reallocations wait for tracked readers/writers before mutating the backing object, so the implementation is safe even when only one physical buffer exists. Targeted double buffers can still be introduced later for performance/overlap (`PreComputedSdf`, `DistanceInitBuffer`, low-res preview images, and small parameter/command buffers), but they are no longer required to prevent cross-queue memory-object races.
+
+## Safe mode
+
+Guarded GPU access uses the conservative serialized mode by default. Each guarded launch drains tracked GPU work before enqueue and waits for its own returned event before returning. This is slower than maximally overlapping command queues, but it keeps the production behavior deterministic and avoids environment-dependent synchronization semantics.
+
+## Adding a new kernel launch
+
+1. Identify every shared OpenCL buffer/image argument.
+2. Capture the relevant generation handles before enqueue.
+3. Create a `GpuKernelAccessGuard` with read/write modes.
+4. Pass `guard.waitEvents()` into `CLProgram::runNonBlockingWithWaitList(...)`.
+5. Call `guard.complete(returnedEvent)` immediately after a successful enqueue.
+
+If a launch cannot declare all shared resources yet, prefer a conservative whole-resource access over leaving the path untracked.
diff --git a/gladius/CMakeLists.txt b/gladius/CMakeLists.txt
@@ -101,7 +101,21 @@ include(cmake/Coverage.cmake)
 set(CMAKE_SKIP_INSTALL_ALL_DEPENDENCY OFF)
 
 if (MSVC)
-    add_compile_options(/bigobj /utf-8 /Zc:__cplusplus)
+    # /Zm200 gives MSVC more internal compiler heap for large template-heavy translation units.
+    # Keep it global so executable-only sources such as the MCP tools get the same protection as libraries.
+    add_compile_options(/bigobj /utf-8 /Zc:__cplusplus /Zm200 /WX)
+
+    if(CMAKE_GENERATOR MATCHES "Ninja")
+      set(GLADIUS_MSVC_COMPILE_JOBS "2" CACHE STRING "Maximum concurrent MSVC compile jobs for Ninja builds")
+      set(GLADIUS_MSVC_HEAVY_COMPILE_JOBS "1" CACHE STRING "Maximum concurrent memory-heavy MSVC compile jobs for Ninja builds")
+
+      set_property(GLOBAL PROPERTY JOB_POOLS
+        gladius_msvc_compile_pool=${GLADIUS_MSVC_COMPILE_JOBS}
+        gladius_msvc_heavy_compile_pool=${GLADIUS_MSVC_HEAVY_COMPILE_JOBS}
+        gladius_msvc_link_pool=1)
+      set(CMAKE_JOB_POOL_COMPILE gladius_msvc_compile_pool)
+      set(CMAKE_JOB_POOL_LINK gladius_msvc_link_pool)
+    endif()
 
     if (CMAKE_BUILD_TYPE STREQUAL "Debug")
         add_compile_options(/RTC1) 
@@ -123,6 +137,9 @@ if (MSVC)
 
     # no console
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup")
+else()
+    # Treat all compiler warnings as errors on GCC/Clang to keep the Linux build clean.
+    add_compile_options(-Werror)
 endif()
 add_definitions(-DTBB_SUPPRESS_DEPRECATED_MESSAGES -DNOMINMAX)
 

diff --git a/gladius/CMakePresets.json b/gladius/CMakePresets.json
@@ -23,8 +23,10 @@
                 "VCPKG_TARGET_TRIPLET": "x64-windows-gladius",
                 "VCPKG_OVERLAY_TRIPLETS": "${sourceDir}/vcpkg-triplets",
                 "VCPKG_OVERLAY_PORTS": "${sourceDir}/vcpkg-overlay-ports",
-                "CMAKE_BUILD_PARALLEL_LEVEL": "8",
                 "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+            },
+            "environment": {
+                "CMAKE_BUILD_PARALLEL_LEVEL": "8"
             }
         },
         {
@@ -111,7 +113,9 @@
                 "VCPKG_OVERLAY_PORTS": "${sourceDir}/vcpkg-overlay-ports",
                 "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
                 "ENABLE_COVERAGE": "OFF",
-                "ENABLE_TRACY": "TRUE",
+                "ENABLE_TRACY": "TRUE"
+            },
+            "environment": {
                 "CMAKE_BUILD_PARALLEL_LEVEL": "8"
             }
         },
@@ -154,6 +158,58 @@
         }
     ],
     "version": 3,
+    "buildPresets": [
+        {
+            "name": "x64-debug",
+            "displayName": "x64 Debug",
+            "configurePreset": "x64-debug",
+            "jobs": 2
+        },
+        {
+            "name": "x64-release",
+            "displayName": "x64 Release",
+            "configurePreset": "x64-release",
+            "jobs": 2
+        },
+        {
+            "name": "x64-release-debug",
+            "displayName": "x64 Release with Debug",
+            "configurePreset": "x64-release-debug",
+            "jobs": 2
+        },
+        {
+            "name": "x64-release-debug-asan",
+            "displayName": "x64 Release with Debug and ASAN",
+            "configurePreset": "x64-release-debug-asan",
+            "jobs": 2
+        },
+        {
+            "name": "x64-release-debug-noOpenCL",
+            "displayName": "x64 Release with Debug (No OpenCL Tests)",
+            "configurePreset": "x64-release-debug-noOpenCL",
+            "jobs": 2
+        },
+        {
+            "name": "linux-debug",
+            "configurePreset": "linux-debug",
+            "jobs": 8
+        },
+        {
+            "name": "linux-release",
+            "configurePreset": "linux-release",
+            "jobs": 8
+        },
+        {
+            "name": "linux-releaseWithDebug",
+            "configurePreset": "linux-releaseWithDebug",
+            "jobs": 8
+        },
+        {
+            "name": "linux-releaseWithDebug-noOpenCL",
+            "configurePreset": "linux-releaseWithDebug-noOpenCL",
+            "jobs": 8
+        }
+    ],
     "testPresets": [
         {
             "name": "ReleaseWithDebug",

diff --git a/gladius/library/mechanical/helix_spring.3mf b/gladius/library/mechanical/helix_spring.3mf
diff --git a/gladius/library/mechanical/involute_gear.3mf b/gladius/library/mechanical/involute_gear.3mf
diff --git a/gladius/library/mechanical/iso_external_thread.3mf b/gladius/library/mechanical/iso_external_thread.3mf
diff --git a/gladius/library/mechanical/metric_nut.3mf b/gladius/library/mechanical/metric_nut.3mf
diff --git a/gladius/library/mechanical/socket_cap_screw.3mf b/gladius/library/mechanical/socket_cap_screw.3mf
diff --git a/gladius/library/mechanical/tube.3mf b/gladius/library/mechanical/tube.3mf
diff --git a/gladius/library/operations/polar_repetition.3mf b/gladius/library/operations/polar_repetition.3mf
diff --git a/gladius/library/operations/twist.3mf b/gladius/library/operations/twist.3mf
diff --git a/gladius/library/primitives/capsule.3mf b/gladius/library/primitives/capsule.3mf
diff --git a/gladius/library/primitives/cone.3mf b/gladius/library/primitives/cone.3mf
diff --git a/gladius/library/primitives/cylinder.3mf b/gladius/library/primitives/cylinder.3mf
diff --git a/gladius/library/primitives/diamond.3mf b/gladius/library/primitives/diamond.3mf
diff --git a/gladius/library/primitives/ellipsoid.3mf b/gladius/library/primitives/ellipsoid.3mf
diff --git a/gladius/library/primitives/hexagon.3mf b/gladius/library/primitives/hexagon.3mf
diff --git a/gladius/library/primitives/rounded_box.3mf b/gladius/library/primitives/rounded_box.3mf
diff --git a/gladius/library/primitives/sphere.3mf b/gladius/library/primitives/sphere.3mf
diff --git a/gladius/library/primitives/torus.3mf b/gladius/library/primitives/torus.3mf
diff --git a/gladius/library/primitives/triangular_prism.3mf b/gladius/library/primitives/triangular_prism.3mf
diff --git a/gladius/library/primitives/truncated_cone.3mf b/gladius/library/primitives/truncated_cone.3mf
diff --git a/gladius/src/Buffer.h b/gladius/src/Buffer.h
@@ -3,6 +3,7 @@
 #include "ComputeContext.h"
 #include <cmath>
 #include <iostream>
+#include <stdexcept>
 #include <typeinfo>
 #include <vector>
 
@@ -14,19 +15,31 @@ namespace gladius
       public:
         explicit Buffer(ComputeContext & context)
             : m_ComputeContext(context)
+            , m_gpuResource(m_ComputeContext.gpuAccessCoordinator().registerResource(
+                GpuResourceKind::Buffer, typeid(T).name()))
         {
         }
 
         ~Buffer()
         {
-            // Release tracked bytes when buffer goes out of scope
-            if (m_buffer && m_size > 0)
+            try
             {
-                m_ComputeContext.onBufferReleased(sizeof(T) * m_size);
+                // Release tracked bytes only after known GPU users have completed.
+                if (m_buffer && m_size > 0)
+                {
+                    m_ComputeContext.waitForGpuResourceIdle(m_gpuResource);
+                    m_ComputeContext.onBufferReleased(sizeof(T) * m_size);
+                }
+            }
+            catch (...)
+            {
+                // Destructors must not throw.
             }
         }
         Buffer(Buffer const & other)
             : m_ComputeContext(other.m_ComputeContext)
+            , m_gpuResource(m_ComputeContext.gpuAccessCoordinator().registerResource(
+                GpuResourceKind::Buffer, typeid(T).name()))
             , m_data(other.m_data)
         {
             create();
@@ -44,6 +57,7 @@ namespace gladius
             {
                 throw std::runtime_error("Failed to read, device buffer could not be created");
             }
+            m_ComputeContext.waitForGpuResourceIdle(m_gpuResource);
             m_data.resize(m_size);
             CL_ERROR(m_ComputeContext.GetQueue().enqueueReadBuffer(
               *m_buffer.get(), CL_TRUE, 0, sizeof(T) * m_size, &m_data[0]));
@@ -59,6 +73,7 @@ namespace gladius
             // If there was a previous allocation, release its accounting first
             if (m_buffer && m_size > 0)
             {
+                retireCurrentGpuGeneration();
                 m_ComputeContext.onBufferReleased(sizeof(T) * m_size);
             }
 
@@ -73,6 +88,7 @@ namespace gladius
             m_data.clear();
             if (m_buffer && m_size > 0)
             {
+                retireCurrentGpuGeneration();
                 m_ComputeContext.onBufferReleased(sizeof(T) * m_size);
             }
             m_size = 0;
@@ -95,6 +111,7 @@ namespace gladius
                 throw std::runtime_error("Failed to write, device buffer could not be created");
             }
 
+            retireCurrentGpuGeneration();
             CL_ERROR(m_ComputeContext.GetQueue().enqueueWriteBuffer(
               *m_buffer.get(), CL_TRUE, 0, sizeof(T) * m_data.size(), &m_data[0]));
 
@@ -139,10 +156,39 @@ namespace gladius
             return *m_buffer.get();
         }
 
+        [[nodiscard]] GpuResourceHandle gpuResourceHandle() const noexcept
+        {
+            return m_gpuResource;
+        }
+
       private:
+        void retireCurrentGpuGeneration()
+        {
+            m_ComputeContext.waitForGpuResourceIdle(m_gpuResource);
+
+            auto retirement = m_ComputeContext.gpuAccessCoordinator().retireCurrentGeneration(
+              m_gpuResource.resourceId);
+            if (retirement.status == GpuAccessStatus::PendingAccessWithoutEvent)
+            {
+                m_ComputeContext.waitForGpuResourceIdle(m_gpuResource);
+                retirement = m_ComputeContext.gpuAccessCoordinator().retireCurrentGeneration(
+                  m_gpuResource.resourceId);
+            }
+
+            if (!retirement.granted())
+            {
+                throw std::runtime_error("Failed to retire GPU buffer generation safely");
+            }
+
+            m_ComputeContext.waitForGpuEvents(retirement.waitEvents);
+            m_ComputeContext.gpuAccessCoordinator().collectCompletedRetirements();
+            m_gpuResource = retirement.newGeneration;
+        }
+
+        ComputeContext & m_ComputeContext;
+        GpuResourceHandle m_gpuResource{};
         std::vector<T> m_data;
         size_t m_size = 0;
-        ComputeContext & m_ComputeContext;
         std::unique_ptr<cl::Buffer> m_buffer;
     };
 }