# Quantum documentation

> Complete documentation, generated from the same source content and MCP catalog as the website.

---

Source: [https://quantum.worldwidewebb.co/docs.md](https://quantum.worldwidewebb.co/docs.md)

# Documentation

A small world starts with a good first step.

Quantum is a macOS desktop voxel editor with an MCP interface and a native Rust/GPUI workspace. Create with an agent, work by hand, or move between both in a native session.

- [**Getting started**Install the app, connect a host, and make your first model.](https://quantum.worldwidewebb.co/docs/getting-started.md)
- [**MCP tools**The actual server catalog, with parameters and complete schemas.](https://quantum.worldwidewebb.co/docs/mcp.md)
- [**The .voxl format**Portable projects, canonical JSON, and the rules on disk.](https://quantum.worldwidewebb.co/docs/format.md)
- [**Agent skills**Reusable workflows for composition, palettes and visual review.](https://quantum.worldwidewebb.co/docs/skills.md)
- [**Plugins**Built-in features, the core boundary, and writing a plugin.](https://quantum.worldwidewebb.co/docs/plugins.md)

## Choose your workspace

| Workspace     | Best for                                            | Agent connection                           |
| ------------- | --------------------------------------------------- | ------------------------------------------ |
| Native editor | Hands-on editing and watching an agent work         | Local Unix socket through the stdio bridge |
| Headless MCP  | Scripted creation and CPU renders without a display | Stdio, with a project directory            |

These docs describe the implementation on the development branch. The [native Mac download](https://quantum.worldwidewebb.co/download/) is Developer ID signed and notarized by Apple, and checks for updates automatically from version 0.3.0.

Everything stays local. No account, cloud relay, or model-provider key is required by Quantum, and your projects never leave your machine. This website uses cookie-free Vercel Web Analytics and Speed Insights for anonymous page-view and performance counts; nothing you build is collected. Your chosen agent host may have its own requirements.

---

Source: [https://quantum.worldwidewebb.co/docs/getting-started.md](https://quantum.worldwidewebb.co/docs/getting-started.md)

# Getting started

Install Quantum. Connect your agent. Make your first model.

- [Download for Mac](https://quantum.worldwidewebb.co/download/)
- [Connect MCP](https://quantum.worldwidewebb.co/docs/getting-started/#connect)

## Build from source

Install Rust with rustup, then run from a repository checkout. The pinned toolchain is Rust 1.99.1.

```sh
export PATH="$HOME/.cargo/bin:$PATH"
cargo build --locked --release \
  -p quantum-app -p quantum-mcp
./target/release/quantum
```

[Download the native Mac app](https://quantum.worldwidewebb.co/download/) for macOS 13+ on Apple silicon, with installation instructions. The app is Developer ID signed and notarized by Apple, and checks for updates automatically from version 0.3.0. Homebrew packages are not available yet. On macOS, install the Xcode command line tools (`xcode-select --install`) before building. This native target is wired through GPUI, but has not been built on this Linux machine. Linux native compilation and capture are verified with X11/Xvfb and Mesa software rendering.

Linux build and desktop dependencies (Debian / Ubuntu)

```sh
sudo apt-get install build-essential pkg-config clang libclang-dev \
  libxkbcommon-dev libxkbcommon-x11-dev libwayland-dev libvulkan-dev \
  libx11-xcb-dev libxcb1-dev libfontconfig-dev libasound2-dev libssl-dev \
  mesa-vulkan-drivers dbus-x11 xdg-desktop-portal xdg-desktop-portal-gtk
```

A display server and a desktop portal are needed for native windows and file dialogs. Headless MCP builds need no display or GPU:

```sh
cargo build --locked --release -p quantum-mcp
cargo test -p quantum-app --no-default-features
```

## Build the website

```sh
scripts/build-site.sh
python3 -m http.server 8090 --directory site --bind 127.0.0.1
```

Open `http://127.0.0.1:8090`. The script generates the static website, documentation and downloadable agent instructions from repository sources.

## Make your first edit by hand

The desktop welcome window shows recent projects with previews. Use Tab to focus Recent, then Up/Down and Enter to open a project. Window → Welcome reopens it; File → Open Recent offers the same history. Clear Recent Projects removes the list without deleting your files.

1.  On desktop, choose New Project or Open… in the welcome window, or double-click a recent project. To explore Autumn Workshop, open `examples/autumn-workshop.voxl`. Right-drag to orbit; wheel to zoom; press F to frame.
2.  Select a visible, unlocked layer and a palette swatch. Press B to place on a face, E to erase, or P to paint.
3.  Use Ctrl/Cmd + Z to undo. Ctrl/Cmd + K opens command search.
4.  Choose File → Save As for your own `.voxl`. Export GLB or PNG through the File menu or command search.

## Connect your agent

The Mac app includes the MCP server. For source builds, build `quantum-mcp` first. Each standalone process owns its own in-memory documents.

### Headless: create and save independently

[Install MCP in Cursor, Claude Code, Codex, VS Code or another host](https://quantum.worldwidewebb.co/docs/mcp/#install-mcp). The guide includes one-click links, CLI commands and manual configuration. Use an existing project directory as the file root, restart your host, list tools and call `quantum_capabilities_get`; expect API `voxelite.v1`. [Install agent skills](https://quantum.worldwidewebb.co/docs/skills/#install-skills) to teach the creative workflow.

### Native: work in the same document

```sh
./target/release/quantum examples/autumn-workshop.voxl --session-socket /tmp/quantum-session.sock
```

Use the MCP executable from the install guide, replacing its arguments with `["--connect", "/tmp/quantum-session.sock"]`. The socket path must not already exist. Or copy the configuration from Agent → Agent connection in the editor. Discover the existing model with capabilities; do not create a second document.

Watch committed calls in Session, pause new writes, and undo or edit by hand. The attached catalog excludes document create/open/save: the native editor owns file lifecycle. Save through the app.

## Your first model through MCP

In standalone mode, ask your connected agent:

> Build a 32 × 32 × 32 clay tower using one atomic box batch. Discover the epoch first. Inspect iso, front, right, and back PNGs, then save first-tower.voxl and export first-tower.glb. Use returned IDs and revisions for each write.

A minimal call sequence follows. These are tool argument objects, not full JSON-RPC messages. Replace placeholders with returned values, and generate a fresh UUID for each new mutation.

### 1\. Discover, then create

Call `quantum_capabilities_get` with `{}`, then `quantum_document_create`:

```json
{
  "name": "First tower",
  "bounds": {"min": [0, 0, 0], "max": [32, 32, 32]},
  "expected_epoch": "<returned epoch>",
  "operation_id": "<fresh UUID>"
}
```

### 2\. Batch the blockout

Call `quantum_voxels_batch`. A new project has a Base layer and clay at slot 1.

```json
{
  "model_id": "<returned model_id>",
  "expected_epoch": "<returned epoch>",
  "expected_revision": "<current revision>",
  "operation_id": "<fresh UUID>",
  "label": "Block out tower",
  "operations": [
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [10, 0, 10], "max": [22, 2, 22]}},
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [13, 2, 13], "max": [19, 18, 19]}},
    {"kind": "box", "layer": "Base", "slot": 1,
     "region": {"min": [11, 18, 11], "max": [21, 20, 21]}}
  ]
}
```

### 3\. Inspect real pixels

Call `quantum_render` and inspect the returned image block:

```json
{
  "model_id": "<returned model_id>",
  "views": ["iso", "front", "right", "back"],
  "width": 512, "height": 512,
  "image_mode": "contact_sheet",
  "revision": "<current revision>"
}
```

### 4\. Save the result

Call `quantum_document_save` with the latest captured revision:

```json
{
  "model_id": "<returned model_id>",
  "expected_epoch": "<returned epoch>",
  "expected_revision": "<current revision>",
  "operation_id": "<fresh UUID>",
  "path": "first-tower.voxl"
}
```

Then call [quantum\_export\_glb](https://quantum.worldwidewebb.co/docs/mcp/#quantum_export_glb). Exports use `revision`, without mutation guards or operation IDs:

```json
{
  "model_id": "<returned model_id>",
  "revision": "<current revision>",
  "path": "first-tower.glb"
}
```

Save before disconnecting: edits and undo history live in memory. Existing export paths reject; choose a fresh output name.

## When a call fails

Check `isError` and the structured envelope's `ok` flag. On a revision conflict, read current state and rebase. On a lost response, retry only the identical request with the same operation ID in the same session. Never guess whether an edit committed. [Read the error guide](https://quantum.worldwidewebb.co/docs/mcp/#errors) before retrying.

## Crash reports and feedback privacy

Quantum has no analytics, telemetry or third-party crash service. A Rust panic writes a local report under `~/Library/Application Support/quantum/crashes/` on macOS (on Linux, the app data directory under `$XDG_DATA_HOME/quantum` or `~/.local/share/quantum`). Reports contain the app version, operating-system name/version, architecture, panic message, source location, backtrace, UTC timestamp and up to 20 recent warning/error log lines. Home-directory prefixes become `~` and email-like text is redacted before storage and again before preview. Other paths, filenames or details in diagnostics may remain: review the complete preview. Scene contents and document metadata are never collected by this flow. Fatal signals, aborts, stack overflow and allocation failures may not produce a report.

On the next launch, including Welcome, you can review the full report, add context, keep it for later, copy or save the redacted preview, or delete the local report. Nothing is sent automatically. **Help → Send feedback…** uses the same preview and confirmation flow for bug reports or feature requests, with version and OS information. Editing your description or report kind invalidates the preview until you update it.

**Continue to GitHub…** opens a prefilled issue form in your browser at `https://github.com/0x63616c/quantum`, using the Bug or Feature template and matching label. This sends the preview to GitHub as part of the URL (and may leave it in browser history). A GitHub account and a separate Submit action there are required to publish the issue. Issues are public. No relay endpoint is configured, so private email contact and scene attachments are unavailable; there is no app token. For a report too large for a browser link, copy or save the full preview and paste it into a new issue yourself. Opening the browser does not prove submission, so crash reports remain local until you explicitly delete them. Pending reports have no automatic expiry; delete them in the prompt or remove their local files.

---

Source: [https://quantum.worldwidewebb.co/docs/mcp.md](https://quantum.worldwidewebb.co/docs/mcp.md)

# MCP tools

Coordinates in. Models out. Real visual feedback.

This reference is generated from the Rust server's live discovery catalog, API `voxelite.v1`. Download the [complete JSON catalog](https://quantum.worldwidewebb.co/assets/mcp-tools.json). Run `quantum-mcp --schema` to inspect the catalog for your own build.

## Install MCP

[Install Quantum for Mac](https://quantum.worldwidewebb.co/download/) in Applications first. The app includes the MCP server. Open your project folder in your host, then choose an install method below. For [source builds](https://quantum.worldwidewebb.co/docs/getting-started/#build) or a different app location, use the manual configuration with your executable's absolute path.

### Cursor

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quantum&config=eyJjb21tYW5kIjoiL0FwcGxpY2F0aW9ucy9RdWFudHVtLmFwcC9Db250ZW50cy9NYWNPUy9xdWFudHVtLW1jcCIsImFyZ3MiOlsiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19)

Review and confirm the server in Cursor. The file root is `${workspaceFolder}`, your open project folder. [View mcp.json](https://quantum.worldwidewebb.co/assets/integrations/cursor/mcp.json) for manual setup.

### Claude Code

Run from your project directory; `"$PWD"` sets the file root to that directory.

```sh
claude mcp add quantum -- '/Applications/Quantum.app/Contents/MacOS/quantum-mcp' --root "$PWD"
```

To make the server available across projects, add `--scope user` after `claude mcp add`. Its file root still points to the directory where you ran the command.

### Codex

Run from your project directory; `"$PWD"` sets the file root to that directory.

```sh
codex mcp add quantum -- '/Applications/Quantum.app/Contents/MacOS/quantum-mcp' --root "$PWD"
```

Or merge this into `~/.codex/config.toml` (or your trusted project's `.codex/config.toml`). Replace `<project dir>` with an existing absolute path.

```toml
[mcp_servers.quantum]
command = "/Applications/Quantum.app/Contents/MacOS/quantum-mcp"
args = ["--root","<project dir>"]
```

### VS Code

[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22quantum%22%2C%22command%22%3A%22%2FApplications%2FQuantum.app%2FContents%2FMacOS%2Fquantum-mcp%22%2C%22args%22%3A%5B%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D)

Review and confirm the server in VS Code, or run this CLI command. Both use `${workspaceFolder}` for the file root, resolved by VS Code in your open project.

```sh
code --add-mcp '{"name":"quantum","command":"/Applications/Quantum.app/Contents/MacOS/quantum-mcp","args":["--root","${workspaceFolder}"]}'
```

[View .vscode/mcp.json](https://quantum.worldwidewebb.co/assets/integrations/vscode/mcp.json) for manual setup.

### Other

For Claude Desktop, Windsurf and other MCP hosts, merge this entry into the host's MCP settings. Preserve existing servers and replace `<project dir>` with an existing absolute path.

```json
{
  "mcpServers": {
    "quantum": {
      "command": "/Applications/Quantum.app/Contents/MacOS/quantum-mcp",
      "args": [
        "--root",
        "<project dir>"
      ]
    }
  }
}
```

## Install skills

Install all skills from the repository's `skills/` directory with the open Agent Skills CLI. This installs workflow instructions; configure MCP above to give them tools.

```sh
npx skills add 0x63616c/quantum
```

Add `--skill <name>` for one skill, `-g` for a global install, or `-a claude-code`, `-a cursor` or `-a codex` to pick an agent. [Choose an individual skill](https://quantum.worldwidewebb.co/docs/skills/#available-skills).

For a manual install, [download the skill folders](https://quantum.worldwidewebb.co/assets/quantum-skills.zip) or use a repository checkout. Copy each `skills/<name>/` folder into `.cursor/skills/`, `.claude/skills/`, or `~/.codex/skills/`. [Install, update and removal notes](https://quantum.worldwidewebb.co/assets/skills/README.md).

## What you get

MCP gives your agent voxel editing tools, palettes, real PNG renders, and project save/export. Skills teach it to compose, inspect and refine a model. Each standalone server owns its own session; save `.voxl` files before disconnecting. To edit the live native canvas, [copy the connection configuration from the app](https://quantum.worldwidewebb.co/docs/getting-started/#connect).

## Verify it works

1.  Restart or reconnect your host and list its MCP tools.
2.  Call `quantum_capabilities_get` with `{}`. Expect API `voxelite.v1`, an epoch and available document IDs.
3.  Confirm the installed skills appear in your host, then ask it to use `quantum-workflow` for your first model.

## Shared contract

*   Stdio uses one JSON-RPC message per line. Stdout contains protocol messages only; diagnostics go to stderr.
*   Supported protocol profiles: `2025-11-25` (initialize and initialized notification) and `2026-07-28` (per-request protocol metadata).
*   Discover the epoch with `quantum_capabilities_get`. Writes use captured `expected_epoch`, a decimal-string `expected_revision` where required, and a fresh UUID `operation_id`.
*   Coordinate order is `[x, y, z]`, right-handed, Y up. Regions include `min` and exclude `max`. Slots are stable IDs, not display positions; zero means air only where the schema allows it.
*   Prefer layer UUIDs and stable slot numbers. Names must resolve uniquely. Unknown fields are rejected, including nested fields.
*   Atomic batches commit one undo entry or nothing. Content-edit results report revision, changed bounds/counts and history IDs. Check the result before updating your local state.
*   The same success JSON appears in `structuredContent` and the first text block. It contains `api_version`, `session_id`, `epoch`, `ok`, and `data` or `error`.

The attached native catalog omits `document_create`, `document_open`, and `document_save`. Use the native UI for file lifecycle. No screenshot-named tool or ellipsoid/cylinder tool is currently exposed: use `quantum_render` for model images and explicit voxel batches for other shapes.

## Render feedback

Default views are iso/front/right/back at 512 × 512 each, returned as a 1024 × 1024 contact sheet. `image_mode` can return individual images, a sheet, or both. Images are actual PNG MCP image blocks, never a simulated preview.

At most six views, 1024 × 1024 per view and 4,194,304 combined view/sheet pixels are allowed, with a 12 MiB encoded response budget. Front looks from +Z, right from +X, top from +Y with −Z up. Explicit cameras and named views are mutually exclusive. Lower dimensions or view count after a budget error.

## Errors, retries and files

| Code                                    | Next step                                                                         |
| --------------------------------------- | --------------------------------------------------------------------------------- |
| `revision_conflict`, `epoch_conflict`   | Read the current model/session, rebase the intended edit, use a new operation ID. |
| `operation_id_reused`                   | Recover the original request. A retry must have identical tool, arguments and ID. |
| `layer_blocked`                         | Confirm the target layer; make it visible or editable explicitly if intended.     |
| `history_conflict`                      | Read history and capture the exact current head/redo ID.                          |
| `invalid_argument`, `out_of_bounds`     | Correct the indicated field or half-open bounds.                                  |
| `limit_exceeded`                        | Reduce batch/page/render size. If receipts are exhausted, save and restart.       |
| `external_file_conflict`, `file_exists` | Preserve externally changed content; choose a new output path.                    |
| `path_outside_root`                     | Use a relative path within the configured file root. Parents must exist.          |
| `outcome_unknown`                       | Inspect the destination: rename may have succeeded before directory sync failed.  |

A domain error returns `isError: true` and `ok: false`, with a recovery hint. Transport success alone does not mean an edit succeeded. Cancellation does not undo an already committed edit. Exact retries replay successful receipts only within the current process.

File tools are confined to `--root`. New files are create-only. Saving over a previously opened/saved file requires its recorded hash to match. Save uses a sibling temporary file, sync and atomic installation. Export does not mark a document saved. Undo/retry state is session-local; comments and named versions persist in `.voxl`.

## All 38 tools

Generated directly from `QuantumServer::tools()`. Expand a schema for nested properties, defaults, limits, conditional requirements and the output envelope. A property marked optional may still be required by a schema condition.

- [capabilities\_get](https://quantum.worldwidewebb.co/docs/mcp/#quantum_capabilities_get)
- [comments\_add](https://quantum.worldwidewebb.co/docs/mcp/#quantum_comments_add)
- [comments\_list](https://quantum.worldwidewebb.co/docs/mcp/#quantum_comments_list)
- [comments\_reopen](https://quantum.worldwidewebb.co/docs/mcp/#quantum_comments_reopen)
- [comments\_reply](https://quantum.worldwidewebb.co/docs/mcp/#quantum_comments_reply)
- [comments\_resolve](https://quantum.worldwidewebb.co/docs/mcp/#quantum_comments_resolve)
- [document\_create](https://quantum.worldwidewebb.co/docs/mcp/#quantum_document_create)
- [document\_info](https://quantum.worldwidewebb.co/docs/mcp/#quantum_document_info)
- [document\_open](https://quantum.worldwidewebb.co/docs/mcp/#quantum_document_open)
- [document\_save](https://quantum.worldwidewebb.co/docs/mcp/#quantum_document_save)
- [export\_glb](https://quantum.worldwidewebb.co/docs/mcp/#quantum_export_glb)
- [export\_png](https://quantum.worldwidewebb.co/docs/mcp/#quantum_export_png)
- [history\_read](https://quantum.worldwidewebb.co/docs/mcp/#quantum_history_read)
- [history\_redo](https://quantum.worldwidewebb.co/docs/mcp/#quantum_history_redo)
- [history\_undo](https://quantum.worldwidewebb.co/docs/mcp/#quantum_history_undo)
- [layers\_add](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_add)
- [layers\_list](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_list)
- [layers\_lock](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_lock)
- [layers\_remove](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_remove)
- [layers\_rename](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_rename)
- [layers\_reorder](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_reorder)
- [layers\_visibility](https://quantum.worldwidewebb.co/docs/mcp/#quantum_layers_visibility)
- [palette\_apply\_preset](https://quantum.worldwidewebb.co/docs/mcp/#quantum_palette_apply_preset)
- [palette\_export](https://quantum.worldwidewebb.co/docs/mcp/#quantum_palette_export)
- [palette\_import](https://quantum.worldwidewebb.co/docs/mcp/#quantum_palette_import)
- [palette\_list](https://quantum.worldwidewebb.co/docs/mcp/#quantum_palette_list)
- [palette\_set\_slot](https://quantum.worldwidewebb.co/docs/mcp/#quantum_palette_set_slot)
- [query](https://quantum.worldwidewebb.co/docs/mcp/#quantum_query)
- [render](https://quantum.worldwidewebb.co/docs/mcp/#quantum_render)
- [versions\_list](https://quantum.worldwidewebb.co/docs/mcp/#quantum_versions_list)
- [versions\_restore](https://quantum.worldwidewebb.co/docs/mcp/#quantum_versions_restore)
- [versions\_save](https://quantum.worldwidewebb.co/docs/mcp/#quantum_versions_save)
- [voxels\_batch](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_batch)
- [voxels\_box](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_box)
- [voxels\_erase\_region](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_erase_region)
- [voxels\_fill](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_fill)
- [voxels\_get](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_get)
- [voxels\_set](https://quantum.worldwidewebb.co/docs/mcp/#quantum_voxels_set)

### quantum\_capabilities\_get

Discover voxelite.v1, session epoch, limits, CPU renderer, exact palette presets and open model IDs. Start here; use returned epoch and revisions for edits.

| Argument | Required | Type / constraints |
| -------- | -------- | ------------------ |

Complete input schema

```json
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "api_version": {
          "const": "voxelite.v1"
        },
        "protocol_versions": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "2025-11-25",
              "2026-07-28"
            ]
          },
          "minItems": 2,
          "maxItems": 2
        },
        "limits": {
          "type": "object",
          "properties": {
            "open_documents": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "request_bytes": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "result_bytes": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "batch_operations": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "explicit_voxels": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "read_voxels": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "work_units": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "operation_receipts": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            "receipt_bytes": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            }
          },
          "required": [
            "open_documents",
            "request_bytes",
            "result_bytes",
            "batch_operations",
            "explicit_voxels",
            "read_voxels",
            "work_units",
            "operation_receipts",
            "receipt_bytes"
          ],
          "additionalProperties": true
        },
        "documents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "model_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "revision": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "Captured monotonic revision, encoded as a decimal u64 string."
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "bounds": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32768,
                      "maximum": 32767
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "max": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32767,
                      "maximum": 32768
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "min",
                  "max"
                ],
                "additionalProperties": true,
                "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
              },
              "layers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    },
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128,
                      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
                    },
                    "visible": {
                      "type": "boolean"
                    },
                    "locked": {
                      "type": "boolean"
                    },
                    "voxel_count": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9223372036854775807
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "visible",
                    "locked",
                    "voxel_count"
                  ],
                  "additionalProperties": true
                },
                "minItems": 1,
                "maxItems": 64
              },
              "dirty": {
                "type": "boolean"
              },
              "voxel_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "palette_slots": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              },
              "comments": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "versions": {
                "type": "integer",
                "minimum": 0,
                "maximum": 64
              },
              "head_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "redo_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "model_id",
              "revision",
              "name",
              "bounds",
              "layers",
              "dirty",
              "voxel_count",
              "palette_slots",
              "comments",
              "versions",
              "head_id",
              "redo_id"
            ],
            "additionalProperties": true
          },
          "minItems": 0,
          "maxItems": 8
        },
        "renderer": {
          "const": "cpu"
        },
        "formats": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16
          },
          "minItems": 1,
          "maxItems": 6
        },
        "presets": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32
          },
          "minItems": 1,
          "maxItems": 7
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "api_version",
        "protocol_versions",
        "limits",
        "documents",
        "renderer",
        "formats",
        "presets",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_comments\_add

Create a persistent voxel/region anchored thread. Author is always agent, never caller-supplied. Text is plain text, max 4096 UTF-8 bytes. Returns thread/message IDs; undoable and saved in .voxl.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `anchor`            | Yes      | See schema                                                                                                                           |
| `layer`             | Optional | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `text`              | Yes      | string; maxLength: 4096                                                                                                              |
| `thread_id`         | Optional | string                                                                                                                               |
| `message_id`        | Optional | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "anchor": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "voxel"
            },
            "at": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "kind",
            "at"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "const": "region"
            },
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "kind",
            "min",
            "max"
          ],
          "additionalProperties": false
        }
      ]
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "thread_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "message_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "anchor",
    "text"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "thread_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "message_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "thread_id",
        "message_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_comments\_list

List anchored threads including messages, agent/human roles, resolved state and anchor status. Optional state=open|resolved|all (default all). Thread and message pages default to 50, max 200. message\_offset applies per thread; bind pages with revision.

| Argument         | Required | Type / constraints                                                    |
| ---------------- | -------- | --------------------------------------------------------------------- |
| `model_id`       | Yes      | string                                                                |
| `revision`       | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |
| `state`          | Optional | string; enum: \["open","resolved","all"\]                             |
| `offset`         | Optional | integer; minimum: 0; maximum: 1024                                    |
| `limit`          | Optional | integer; minimum: 1; maximum: 200                                     |
| `message_offset` | Optional | integer; minimum: 0; maximum: 10000                                   |
| `message_limit`  | Optional | integer; minimum: 1; maximum: 200                                     |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "state": {
      "type": "string",
      "enum": [
        "open",
        "resolved",
        "all"
      ]
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1024
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "message_offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "message_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "comments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "thread": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  },
                  "anchor": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "const": "voxel"
                          },
                          "at": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": -32768,
                              "maximum": 32767
                            },
                            "minItems": 3,
                            "maxItems": 3
                          }
                        },
                        "required": [
                          "kind",
                          "at"
                        ],
                        "additionalProperties": true
                      },
                      {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "const": "region"
                          },
                          "min": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": -32768,
                              "maximum": 32767
                            },
                            "minItems": 3,
                            "maxItems": 3
                          },
                          "max": {
                            "type": "array",
                            "items": {
                              "type": "integer",
                              "minimum": -32767,
                              "maximum": 32768
                            },
                            "minItems": 3,
                            "maxItems": 3
                          }
                        },
                        "required": [
                          "kind",
                          "min",
                          "max"
                        ],
                        "additionalProperties": true
                      }
                    ]
                  },
                  "layer": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "resolved": {
                    "type": "boolean"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                        },
                        "origin": {
                          "type": "string",
                          "enum": [
                            "agent",
                            "human"
                          ]
                        },
                        "text": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 8192
                        },
                        "tool": {
                          "anyOf": [
                            {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 128,
                              "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                              "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "origin",
                        "text",
                        "tool"
                      ],
                      "additionalProperties": true
                    },
                    "minItems": 0,
                    "maxItems": 200
                  }
                },
                "required": [
                  "id",
                  "anchor",
                  "layer",
                  "resolved",
                  "messages"
                ],
                "additionalProperties": true
              },
              "message_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "next_message_offset": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9223372036854775807
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "anchor_state": {
                "type": "string",
                "enum": [
                  "visible",
                  "hidden",
                  "orphaned"
                ]
              }
            },
            "required": [
              "thread",
              "message_count",
              "next_message_offset",
              "anchor_state"
            ],
            "additionalProperties": true
          },
          "minItems": 0,
          "maxItems": 200
        },
        "total": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "next_offset": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "comments",
        "total",
        "next_offset"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_comments\_reopen

Reopen a resolved discussion; idempotent if already open. Preserves messages and anchor; undoable.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `thread_id`         | Yes      | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "thread_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "thread_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_comments\_reply

Append an agent-attributed plain-text reply to a thread, resolved or open. One undoable edit; returns message ID.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `thread_id`         | Yes      | string                                                                                                                               |
| `text`              | Yes      | string; maxLength: 4096                                                                                                              |
| `message_id`        | Optional | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "thread_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "message_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "thread_id",
    "text"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "thread_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "message_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "thread_id",
        "message_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_comments\_resolve

Resolve an anchored discussion; idempotent if already resolved. Preserves messages and anchor; undoable.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `thread_id`         | Yes      | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "thread_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "thread_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_document\_create

Create a revision-zero document and visible unlocked Base layer. Default bounds \[0,0,0\]..\[32,32,32\]. Returns model/layer IDs. Up to eight documents per session; never replaces an open model.

| Argument         | Required | Type / constraints                                                                                                                     |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_epoch` | Yes      | string                                                                                                                                 |
| `operation_id`   | Yes      | string                                                                                                                                 |
| `label`          | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime.   |
| `name`           | Yes      | string; maxLength: 128. Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `bounds`         | Optional | object. Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime.          |
| `model_id`       | Optional | string                                                                                                                                 |
| `layer_id`       | Optional | string                                                                                                                                 |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "bounds": {
      "type": "object",
      "properties": {
        "min": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32768,
            "maximum": 32767
          },
          "minItems": 3,
          "maxItems": 3
        },
        "max": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32767,
            "maximum": 32768
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "layer_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
          "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "layers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "visible": {
                "type": "boolean"
              },
              "locked": {
                "type": "boolean"
              },
              "voxel_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "id",
              "name",
              "visible",
              "locked",
              "voxel_count"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 64
        },
        "dirty": {
          "type": "boolean"
        },
        "voxel_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "palette_slots": {
          "type": "integer",
          "minimum": 1,
          "maximum": 256
        },
        "comments": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "versions": {
          "type": "integer",
          "minimum": 0,
          "maximum": 64
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "name",
        "bounds",
        "layers",
        "dirty",
        "voxel_count",
        "palette_slots",
        "comments",
        "versions",
        "head_id",
        "redo_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_document\_info

Read document identity, bounds, layers, counts, dirty state and current revision. Optional revision must equal the live revision; no UI state is used.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
          "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "layers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "visible": {
                "type": "boolean"
              },
              "locked": {
                "type": "boolean"
              },
              "voxel_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "id",
              "name",
              "visible",
              "locked",
              "voxel_count"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 64
        },
        "dirty": {
          "type": "boolean"
        },
        "voxel_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "palette_slots": {
          "type": "integer",
          "minimum": 1,
          "maximum": 256
        },
        "comments": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "versions": {
          "type": "integer",
          "minimum": 0,
          "maximum": 64
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "name",
        "bounds",
        "layers",
        "dirty",
        "voxel_count",
        "palette_slots",
        "comments",
        "versions",
        "head_id",
        "redo_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_document\_open

Open a canonical .voxl file relative to the configured project root, preserving IDs, comments, versions and unknown metadata. Validation finishes before installation. Duplicate model IDs reject.

| Argument         | Required | Type / constraints                                                                                                                   |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch` | Yes      | string                                                                                                                               |
| `operation_id`   | Yes      | string                                                                                                                               |
| `label`          | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `path`           | Yes      | string; maxLength: 1024                                                                                                              |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "path"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
          "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "layers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "visible": {
                "type": "boolean"
              },
              "locked": {
                "type": "boolean"
              },
              "voxel_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "id",
              "name",
              "visible",
              "locked",
              "voxel_count"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 64
        },
        "dirty": {
          "type": "boolean"
        },
        "voxel_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "palette_slots": {
          "type": "integer",
          "minimum": 1,
          "maximum": 256
        },
        "comments": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "versions": {
          "type": "integer",
          "minimum": 0,
          "maximum": 64
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "name",
        "bounds",
        "layers",
        "dirty",
        "voxel_count",
        "palette_slots",
        "comments",
        "versions",
        "head_id",
        "redo_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_document\_save

Atomically save .voxl under the project root. New paths must not exist; overwriting the same opened/saved path checks its last SHA-256. Does not create an undo entry. Changes stay in memory until saved.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `path`              | Yes      | string; maxLength: 1024                                                                                                              |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "path"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "bytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "dirty": {
          "const": false
        }
      },
      "required": [
        "model_id",
        "revision",
        "path",
        "bytes",
        "sha256",
        "dirty"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_export\_glb

Export deterministic GLB of the highest visible layer at each occupied coordinate. Atomically write a new path under project root; existing paths reject. Returns size and SHA-256; document/history unchanged.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |
| `path`     | Yes      | string; maxLength: 1024                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  },
  "required": [
    "model_id",
    "path"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "bytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "mime_type": {
          "const": "model/gltf-binary"
        }
      },
      "required": [
        "model_id",
        "revision",
        "path",
        "bytes",
        "sha256",
        "mime_type"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_export\_png

Render and atomically write one PNG under project root. Default contact sheet; for individual image use one view. Existing paths reject. Returns size, SHA-256 and camera metadata; document/history unchanged.

| Argument                     | Required | Type / constraints                                                                                                                                                              |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model_id`                   | Yes      | string                                                                                                                                                                          |
| `revision`                   | Optional | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                                                           |
| `views`                      | Optional | array; minItems: 1; maxItems: 6                                                                                                                                                 |
| `camera`                     | Optional | object                                                                                                                                                                          |
| `width`                      | Optional | integer; minimum: 1; maximum: 1024                                                                                                                                              |
| `height`                     | Optional | integer; minimum: 1; maximum: 1024                                                                                                                                              |
| `perspective`                | Optional | boolean                                                                                                                                                                         |
| `background`                 | Optional | array; minItems: 4; maxItems: 4                                                                                                                                                 |
| `ambient_occlusion_strength` | Optional | number; default: 1; minimum: 0; maximum: 2. Local voxel contact shading: 0 disables AO, 1 preserves the default look, 2 doubles darkening. Independent of viewport preferences. |
| `image_mode`                 | Optional | string; enum: \["contact\_sheet","individual"\]                                                                                                                                 |
| `path`                       | Yes      | string; maxLength: 1024                                                                                                                                                         |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "views": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "iso",
          "front",
          "back",
          "left",
          "right",
          "top"
        ]
      },
      "minItems": 1,
      "maxItems": 6
    },
    "camera": {
      "type": "object",
      "properties": {
        "eye": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "target": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "up": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "projection": {
          "type": "string",
          "enum": [
            "orthographic",
            "perspective"
          ]
        },
        "ortho_height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000000000.0
        },
        "fov_y_degrees": {
          "type": "number",
          "exclusiveMinimum": 1,
          "exclusiveMaximum": 179
        }
      },
      "required": [
        "eye",
        "target",
        "up",
        "projection"
      ],
      "additionalProperties": false,
      "oneOf": [
        {
          "properties": {
            "projection": {
              "const": "orthographic"
            }
          },
          "required": [
            "ortho_height"
          ],
          "not": {
            "required": [
              "fov_y_degrees"
            ]
          }
        },
        {
          "properties": {
            "projection": {
              "const": "perspective"
            }
          },
          "required": [
            "fov_y_degrees"
          ],
          "not": {
            "required": [
              "ortho_height"
            ]
          }
        }
      ]
    },
    "width": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1024
    },
    "height": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1024
    },
    "perspective": {
      "type": "boolean"
    },
    "background": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 255
      },
      "minItems": 4,
      "maxItems": 4
    },
    "ambient_occlusion_strength": {
      "type": "number",
      "minimum": 0,
      "maximum": 2,
      "default": 1,
      "description": "Local voxel contact shading: 0 disables AO, 1 preserves the default look, 2 doubles darkening. Independent of viewport preferences."
    },
    "image_mode": {
      "type": "string",
      "enum": [
        "contact_sheet",
        "individual"
      ]
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  },
  "required": [
    "model_id",
    "path"
  ],
  "additionalProperties": false,
  "not": {
    "required": [
      "camera"
    ],
    "anyOf": [
      {
        "required": [
          "views"
        ]
      },
      {
        "required": [
          "perspective"
        ]
      }
    ]
  },
  "if": {
    "properties": {
      "image_mode": {
        "const": "individual"
      }
    },
    "required": [
      "image_mode"
    ]
  },
  "then": {
    "anyOf": [
      {
        "required": [
          "camera"
        ]
      },
      {
        "required": [
          "views"
        ],
        "properties": {
          "views": {
            "maxItems": 1
          }
        }
      }
    ]
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "bytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "backend": {
          "const": "cpu"
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "views": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "view": {
                "type": "string",
                "enum": [
                  "iso",
                  "front",
                  "back",
                  "left",
                  "right",
                  "top",
                  "camera",
                  "contact_sheet"
                ]
              },
              "width": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "height": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "camera": {
                "type": "object",
                "properties": {
                  "eye": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "target": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "up": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "projection": {
                    "type": "string",
                    "enum": [
                      "orthographic",
                      "perspective"
                    ]
                  },
                  "ortho_height": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000000.0
                  },
                  "fov_y_degrees": {
                    "type": "number",
                    "exclusiveMinimum": 1,
                    "exclusiveMaximum": 179
                  }
                },
                "required": [
                  "eye",
                  "target",
                  "up",
                  "projection"
                ],
                "additionalProperties": true,
                "oneOf": [
                  {
                    "properties": {
                      "projection": {
                        "const": "orthographic"
                      }
                    },
                    "required": [
                      "ortho_height"
                    ],
                    "not": {
                      "required": [
                        "fov_y_degrees"
                      ]
                    }
                  },
                  {
                    "properties": {
                      "projection": {
                        "const": "perspective"
                      }
                    },
                    "required": [
                      "fov_y_degrees"
                    ],
                    "not": {
                      "required": [
                        "ortho_height"
                      ]
                    }
                  }
                ]
              }
            },
            "required": [
              "view",
              "width",
              "height",
              "sha256",
              "bytes",
              "camera"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 6
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "view": {
                "type": "string",
                "enum": [
                  "iso",
                  "front",
                  "back",
                  "left",
                  "right",
                  "top",
                  "camera",
                  "contact_sheet"
                ]
              },
              "width": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "height": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "view",
              "width",
              "height",
              "sha256",
              "bytes"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 7
        },
        "image_mode": {
          "type": "string",
          "enum": [
            "contact_sheet",
            "individual",
            "both"
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "path",
        "bytes",
        "sha256",
        "backend",
        "bounds",
        "views",
        "images",
        "image_mode"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_history\_read

Read chronological applied history with agent origins, tool names, labels and change summaries. Includes exact undo/redo entry IDs. Default page 50, max 200; history is bounded and resets on reopen.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |
| `offset`   | Optional | integer; minimum: 0; maximum: 1048576                                 |
| `limit`    | Optional | integer; minimum: 1; maximum: 200                                     |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1048576
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "entries": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "entry_id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "origin": {
                "type": "string",
                "enum": [
                  "agent",
                  "human"
                ]
              },
              "tool": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "base_revision": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "Captured monotonic revision, encoded as a decimal u64 string."
              },
              "result_revision": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,19})$",
                "description": "Captured monotonic revision, encoded as a decimal u64 string."
              },
              "added": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "removed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "recolored": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "changed_bounds": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "min": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": -32768,
                          "maximum": 32767
                        },
                        "minItems": 3,
                        "maxItems": 3
                      },
                      "max": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": -32767,
                          "maximum": 32768
                        },
                        "minItems": 3,
                        "maxItems": 3
                      }
                    },
                    "required": [
                      "min",
                      "max"
                    ],
                    "additionalProperties": true,
                    "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "entry_id",
              "origin",
              "tool",
              "label",
              "base_revision",
              "result_revision",
              "added",
              "removed",
              "recolored",
              "changed_bounds"
            ],
            "additionalProperties": true
          },
          "minItems": 0,
          "maxItems": 200
        },
        "total": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "next_offset": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "initial_retained": {
          "type": "boolean"
        },
        "history_bytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        }
      },
      "required": [
        "model_id",
        "revision",
        "entries",
        "total",
        "next_offset",
        "head_id",
        "redo_id",
        "initial_retained",
        "history_bytes"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_history\_redo

Redo exactly the expected redo entry. Requires captured epoch/revision/entry\_id. A new edit clears the redo branch; stale IDs reject.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `entry_id`          | Yes      | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "entry_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "entry_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "redo_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_history\_undo

Undo exactly the expected top entry. Requires captured epoch/revision/entry\_id; intervening edits reject. Revision increases monotonically; original entry retains its agent attribution.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `entry_id`          | Yes      | string                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "entry_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "entry_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "redo_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "redo_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_add

Insert an empty layer at bottom-to-top index (default append). Optional layer\_id supports deterministic references. Maximum 64 layers.

| Argument            | Required | Type / constraints                                                                                                                     |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_epoch`    | Yes      | string                                                                                                                                 |
| `operation_id`      | Yes      | string                                                                                                                                 |
| `model_id`          | Yes      | string                                                                                                                                 |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                  |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime.   |
| `name`              | Yes      | string; maxLength: 128. Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer_id`          | Optional | string                                                                                                                                 |
| `index`             | Optional | integer; minimum: 0; maximum: 64                                                                                                       |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "index": {
      "type": "integer",
      "minimum": 0,
      "maximum": 64
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "layer_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "layer_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_list

List stable layer IDs, exact names, visibility, lock state and stored voxel counts in bottom-to-top order.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "layers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "visible": {
                "type": "boolean"
              },
              "locked": {
                "type": "boolean"
              },
              "voxel_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "id",
              "name",
              "visible",
              "locked",
              "voxel_count"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 64
        }
      },
      "required": [
        "model_id",
        "revision",
        "layers"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_lock

Set lock explicitly. Clear the lock in a separate operation before voxel editing; all mutations share the core lock rules and history.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `locked`            | Yes      | boolean                                                                                                                              |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "locked": {
      "type": "boolean"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "locked"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_remove

Delete one unlocked layer and its voxels as one undoable edit. Final-layer deletion rejects; anchored comments remain and may become orphaned.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_rename

Rename a layer without changing its stable ID. Duplicate names are allowed, but future name-based access must be unambiguous.

| Argument            | Required | Type / constraints                                                                                                                     |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_epoch`    | Yes      | string                                                                                                                                 |
| `operation_id`      | Yes      | string                                                                                                                                 |
| `model_id`          | Yes      | string                                                                                                                                 |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                  |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime.   |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                             |
| `name`              | Yes      | string; maxLength: 128. Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_reorder

Set an exact bottom-to-top permutation of all layer IDs/names. The highest visible layer wins at overlaps; omitted or duplicate layers reject.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `order`             | Yes      | array; minItems: 1; maxItems: 64                                                                                                     |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "order": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
        "description": "Layer UUID or unique exact name. Never inferred from UI selection."
      },
      "minItems": 1,
      "maxItems": 64
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "order"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_layers\_visibility

Set visibility explicitly. Hidden cells stay stored and cannot be edited until made visible. Metadata changes are undoable.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `visible`           | Yes      | boolean                                                                                                                              |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "visible": {
      "type": "boolean"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "visible"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_palette\_apply\_preset

Append exact preset colors into unused slots without recoloring existing voxels. Returns source-to-new slot mapping. Rejects atomically if capacity would exceed 256; originals are immutable.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `preset`            | Yes      | string; enum: \["pico8","endesga32","sweetie16","grayscale","neutral","warm","vivid"\]                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "preset": {
      "type": "string",
      "enum": [
        "pico8",
        "endesga32",
        "sweetie16",
        "grayscale",
        "neutral",
        "warm",
        "vivid"
      ]
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "preset"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "slot_mapping": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              },
              "slot": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              }
            },
            "required": [
              "source",
              "slot"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 256
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "slot_mapping"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_palette\_export

Return palette as .hex, .gpl or JASC-PAL .pal text in display order; GPL preserves representable names. Read-only, no filesystem side effects.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |
| `format`   | Yes      | string; enum: \["hex","gpl","pal"\]                                   |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "format": {
      "type": "string",
      "enum": [
        "hex",
        "gpl",
        "pal"
      ]
    }
  },
  "required": [
    "model_id",
    "format"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 65536
        },
        "format": {
          "type": "string",
          "enum": [
            "hex",
            "gpl",
            "pal"
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "text",
        "format"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_palette\_import

Append colors from bounded .hex, .gpl or JASC-PAL .pal text into unused slots; no implicit geometry recoloring. Returns source-to-new mapping; malformed input or insufficient capacity leaves palette unchanged.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `format`            | Yes      | string; enum: \["hex","gpl","pal"\]                                                                                                  |
| `text`              | Yes      | string; maxLength: 65536                                                                                                             |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "format": {
      "type": "string",
      "enum": [
        "hex",
        "gpl",
        "pal"
      ]
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "format",
    "text"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "slot_mapping": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              },
              "slot": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              }
            },
            "required": [
              "source",
              "slot"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 256
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "slot_mapping"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_palette\_list

List stable palette slots, names, RGBA colors, display order and exact preset names. Slot 0 is reserved for air.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "palette": {
          "type": "object",
          "properties": {
            "slots": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "index": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 256
                  },
                  "rgba": {
                    "type": "array",
                    "prefixItems": [
                      {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 255
                      },
                      {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 255
                      },
                      {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 255
                      },
                      {
                        "const": 255
                      }
                    ],
                    "items": false,
                    "minItems": 4,
                    "maxItems": 4,
                    "description": "Opaque sRGB RGBA8; alpha must equal 255."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                    "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
                  }
                },
                "required": [
                  "index",
                  "rgba"
                ],
                "additionalProperties": true
              },
              "minItems": 1,
              "maxItems": 256
            },
            "order": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              },
              "minItems": 1,
              "maxItems": 256
            }
          },
          "required": [
            "slots",
            "order"
          ],
          "additionalProperties": true
        },
        "presets": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32
          },
          "minItems": 1,
          "maxItems": 7
        }
      },
      "required": [
        "model_id",
        "revision",
        "palette",
        "presets"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_palette\_set\_slot

Add or replace stable slot 1..256 with opaque RGBA. Existing references change appearance, including locked layers. Omitted name creates an unnamed swatch. One undoable edit.

| Argument            | Required | Type / constraints                                                                                                                     |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_epoch`    | Yes      | string                                                                                                                                 |
| `operation_id`      | Yes      | string                                                                                                                                 |
| `model_id`          | Yes      | string                                                                                                                                 |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                  |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime.   |
| `slot`              | Yes      | integer; minimum: 1; maximum: 256                                                                                                      |
| `rgba`              | Yes      | array; minItems: 4; maxItems: 4. Opaque sRGB RGBA8; alpha must equal 255.                                                              |
| `name`              | Optional | string; maxLength: 128. Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "slot": {
      "type": "integer",
      "minimum": 1,
      "maximum": 256
    },
    "rgba": {
      "type": "array",
      "prefixItems": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        {
          "const": 255
        }
      ],
      "items": false,
      "minItems": 4,
      "maxItems": 4,
      "description": "Opaque sRGB RGBA8; alpha must equal 255."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "slot",
    "rgba"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_query

Query bounds, counts or paged occupied voxels within a half-open region. view=layers (default) counts overlaps separately; composite uses highest visible layer. Optional layer restricts stored-layer queries. limit defaults 1000, max 10000. Use returned revision with next\_offset to prevent mixed pages.

| Argument   | Required | Type / constraints                                                                                                            |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                                                                        |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string.                                                         |
| `kind`     | Yes      | string; enum: \["bounds","counts","voxels"\]                                                                                  |
| `region`   | Optional | object. Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime. |
| `layer`    | Optional | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                    |
| `view`     | Optional | string; enum: \["layers","composite"\]                                                                                        |
| `offset`   | Optional | integer; minimum: 0; maximum: 1048576                                                                                         |
| `limit`    | Optional | integer; minimum: 1; maximum: 10000                                                                                           |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "kind": {
      "type": "string",
      "enum": [
        "bounds",
        "counts",
        "voxels"
      ]
    },
    "region": {
      "type": "object",
      "properties": {
        "min": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32768,
            "maximum": 32767
          },
          "minItems": 3,
          "maxItems": 3
        },
        "max": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32767,
            "maximum": 32768
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "view": {
      "type": "string",
      "enum": [
        "layers",
        "composite"
      ]
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1048576
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "model_id",
    "kind"
  ],
  "additionalProperties": false,
  "not": {
    "required": [
      "view",
      "layer"
    ],
    "properties": {
      "view": {
        "const": "composite"
      }
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "region": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "occupied_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "voxel_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "view": {
          "type": "string",
          "enum": [
            "layers",
            "composite"
          ]
        },
        "slots": {
          "type": "object",
          "propertyNames": {
            "pattern": "^[0-9]{1,3}$"
          },
          "additionalProperties": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9223372036854775807
          }
        },
        "next_offset": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9223372036854775807
            },
            {
              "type": "null"
            }
          ]
        },
        "voxels": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "layer_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "at": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": -32768,
                  "maximum": 32767
                },
                "minItems": 3,
                "maxItems": 3
              },
              "slot": {
                "type": "integer",
                "minimum": 1,
                "maximum": 256
              }
            },
            "required": [
              "layer_id",
              "at",
              "slot"
            ],
            "additionalProperties": true
          },
          "minItems": 0,
          "maxItems": 10000
        }
      },
      "required": [
        "model_id",
        "revision",
        "bounds",
        "region",
        "occupied_bounds",
        "voxel_count",
        "view"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_render

Render CPU PNG image content from one immutable revision. Default four views \[iso,front,right,back\] at 512², transparent background, orthographic, 2x AA, labeled contact sheet. Up to six views or one explicit camera; <=4,194,304 combined image/sheet pixels. image\_mode=contact\_sheet|individual|both. Returns camera metadata and hashes; no GPU/display required.

| Argument                     | Required | Type / constraints                                                                                                                                                              |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model_id`                   | Yes      | string                                                                                                                                                                          |
| `revision`                   | Optional | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                                                           |
| `views`                      | Optional | array; minItems: 1; maxItems: 6                                                                                                                                                 |
| `camera`                     | Optional | object                                                                                                                                                                          |
| `width`                      | Optional | integer; minimum: 1; maximum: 1024                                                                                                                                              |
| `height`                     | Optional | integer; minimum: 1; maximum: 1024                                                                                                                                              |
| `perspective`                | Optional | boolean                                                                                                                                                                         |
| `background`                 | Optional | array; minItems: 4; maxItems: 4                                                                                                                                                 |
| `ambient_occlusion_strength` | Optional | number; default: 1; minimum: 0; maximum: 2. Local voxel contact shading: 0 disables AO, 1 preserves the default look, 2 doubles darkening. Independent of viewport preferences. |
| `image_mode`                 | Optional | string; enum: \["contact\_sheet","individual","both"\]                                                                                                                          |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "views": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "iso",
          "front",
          "back",
          "left",
          "right",
          "top"
        ]
      },
      "minItems": 1,
      "maxItems": 6
    },
    "camera": {
      "type": "object",
      "properties": {
        "eye": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "target": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "up": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -1000000000.0,
            "maximum": 1000000000.0
          },
          "minItems": 3,
          "maxItems": 3
        },
        "projection": {
          "type": "string",
          "enum": [
            "orthographic",
            "perspective"
          ]
        },
        "ortho_height": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000000000.0
        },
        "fov_y_degrees": {
          "type": "number",
          "exclusiveMinimum": 1,
          "exclusiveMaximum": 179
        }
      },
      "required": [
        "eye",
        "target",
        "up",
        "projection"
      ],
      "additionalProperties": false,
      "oneOf": [
        {
          "properties": {
            "projection": {
              "const": "orthographic"
            }
          },
          "required": [
            "ortho_height"
          ],
          "not": {
            "required": [
              "fov_y_degrees"
            ]
          }
        },
        {
          "properties": {
            "projection": {
              "const": "perspective"
            }
          },
          "required": [
            "fov_y_degrees"
          ],
          "not": {
            "required": [
              "ortho_height"
            ]
          }
        }
      ]
    },
    "width": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1024
    },
    "height": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1024
    },
    "perspective": {
      "type": "boolean"
    },
    "background": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 255
      },
      "minItems": 4,
      "maxItems": 4
    },
    "ambient_occlusion_strength": {
      "type": "number",
      "minimum": 0,
      "maximum": 2,
      "default": 1,
      "description": "Local voxel contact shading: 0 disables AO, 1 preserves the default look, 2 doubles darkening. Independent of viewport preferences."
    },
    "image_mode": {
      "type": "string",
      "enum": [
        "contact_sheet",
        "individual",
        "both"
      ]
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "not": {
    "required": [
      "camera"
    ],
    "anyOf": [
      {
        "required": [
          "views"
        ]
      },
      {
        "required": [
          "perspective"
        ]
      }
    ]
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "backend": {
          "const": "cpu"
        },
        "bounds": {
          "type": "object",
          "properties": {
            "min": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32768,
                "maximum": 32767
              },
              "minItems": 3,
              "maxItems": 3
            },
            "max": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": -32767,
                "maximum": 32768
              },
              "minItems": 3,
              "maxItems": 3
            }
          },
          "required": [
            "min",
            "max"
          ],
          "additionalProperties": true,
          "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
        },
        "views": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "view": {
                "type": "string",
                "enum": [
                  "iso",
                  "front",
                  "back",
                  "left",
                  "right",
                  "top",
                  "camera",
                  "contact_sheet"
                ]
              },
              "width": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "height": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              },
              "camera": {
                "type": "object",
                "properties": {
                  "eye": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "target": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "up": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "minimum": -1000000000.0,
                      "maximum": 1000000000.0
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "projection": {
                    "type": "string",
                    "enum": [
                      "orthographic",
                      "perspective"
                    ]
                  },
                  "ortho_height": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000000.0
                  },
                  "fov_y_degrees": {
                    "type": "number",
                    "exclusiveMinimum": 1,
                    "exclusiveMaximum": 179
                  }
                },
                "required": [
                  "eye",
                  "target",
                  "up",
                  "projection"
                ],
                "additionalProperties": true,
                "oneOf": [
                  {
                    "properties": {
                      "projection": {
                        "const": "orthographic"
                      }
                    },
                    "required": [
                      "ortho_height"
                    ],
                    "not": {
                      "required": [
                        "fov_y_degrees"
                      ]
                    }
                  },
                  {
                    "properties": {
                      "projection": {
                        "const": "perspective"
                      }
                    },
                    "required": [
                      "fov_y_degrees"
                    ],
                    "not": {
                      "required": [
                        "ortho_height"
                      ]
                    }
                  }
                ]
              }
            },
            "required": [
              "view",
              "width",
              "height",
              "sha256",
              "bytes",
              "camera"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 6
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "view": {
                "type": "string",
                "enum": [
                  "iso",
                  "front",
                  "back",
                  "left",
                  "right",
                  "top",
                  "camera",
                  "contact_sheet"
                ]
              },
              "width": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "height": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2048
              },
              "sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "bytes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9223372036854775807
              }
            },
            "required": [
              "view",
              "width",
              "height",
              "sha256",
              "bytes"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 7
        },
        "image_mode": {
          "type": "string",
          "enum": [
            "contact_sheet",
            "individual",
            "both"
          ]
        }
      },
      "required": [
        "model_id",
        "revision",
        "backend",
        "bounds",
        "views",
        "images",
        "image_mode"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_versions\_list

List named version IDs, names, parent IDs, origin and immutable content hashes. Persistent across save/open; independent of undo retention. Never includes full voxel snapshots.

| Argument   | Required | Type / constraints                                                    |
| ---------- | -------- | --------------------------------------------------------------------- |
| `model_id` | Yes      | string                                                                |
| `revision` | Optional | string. Captured monotonic revision, encoded as a decimal u64 string. |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    }
  },
  "required": [
    "model_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "versions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
              },
              "parent_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "origin": {
                "type": "string",
                "enum": [
                  "agent",
                  "human"
                ]
              },
              "content_hash": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              }
            },
            "required": [
              "id",
              "name",
              "parent_id",
              "origin",
              "content_hash"
            ],
            "additionalProperties": true
          },
          "minItems": 0,
          "maxItems": 64
        }
      },
      "required": [
        "model_id",
        "revision",
        "versions"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_versions\_restore

Restore named content as a new undoable edit, keeping the version library. Requires expected\_head\_id (null for empty history) in addition to revision/epoch. Core validates current locks before installation.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `version_id`        | Yes      | string                                                                                                                               |
| `expected_head_id`  | Yes      | See schema                                                                                                                           |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "version_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_head_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "version_id",
    "expected_head_id"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_versions\_save

Persist current content as a named immutable snapshot with agent attribution and content hash. Up to 64 versions, no recursive libraries. One undoable library edit; save document to retain across process restarts.

| Argument            | Required | Type / constraints                                                                                                                     |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_epoch`    | Yes      | string                                                                                                                                 |
| `operation_id`      | Yes      | string                                                                                                                                 |
| `model_id`          | Yes      | string                                                                                                                                 |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                  |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime.   |
| `name`              | Yes      | string; maxLength: 128. Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `version_id`        | Optional | string                                                                                                                                 |
| `parent_id`         | Optional | string                                                                                                                                 |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 128 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "version_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "parent_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "name"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        },
        "version_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability",
        "version_id"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_batch

Apply 1..256 ordered voxel operations atomically to one model: set, erase\_region, fill, box. Each operation names its own layer/mirror; nesting and I/O are forbidden. Later operations see earlier edits; any failure rolls back all; one revision and undo entry.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `operations`        | Yes      | array; minItems: 1; maxItems: 256                                                                                                    |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "operations": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "layer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Layer UUID or unique exact name. Never inferred from UI selection."
              },
              "voxels": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "at": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": -32768,
                        "maximum": 32767
                      },
                      "minItems": 3,
                      "maxItems": 3
                    },
                    "slot": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 256
                        },
                        {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128
                        }
                      ],
                      "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
                    }
                  },
                  "required": [
                    "at",
                    "slot"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "maxItems": 65536
              },
              "mode": {
                "type": "string",
                "enum": [
                  "place",
                  "paint"
                ]
              },
              "mirror": {
                "type": "object",
                "properties": {
                  "axes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "y",
                        "z"
                      ]
                    },
                    "minItems": 0,
                    "maxItems": 3,
                    "uniqueItems": true
                  },
                  "plane2": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -65536,
                      "maximum": 65536
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "axes",
                  "plane2"
                ],
                "additionalProperties": false
              },
              "kind": {
                "const": "set"
              }
            },
            "required": [
              "layer",
              "voxels",
              "kind"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "layer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Layer UUID or unique exact name. Never inferred from UI selection."
              },
              "region": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32768,
                      "maximum": 32767
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "max": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32767,
                      "maximum": 32768
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "min",
                  "max"
                ],
                "additionalProperties": false,
                "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
              },
              "mirror": {
                "type": "object",
                "properties": {
                  "axes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "y",
                        "z"
                      ]
                    },
                    "minItems": 0,
                    "maxItems": 3,
                    "uniqueItems": true
                  },
                  "plane2": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -65536,
                      "maximum": 65536
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "axes",
                  "plane2"
                ],
                "additionalProperties": false
              },
              "kind": {
                "const": "erase_region"
              }
            },
            "required": [
              "layer",
              "region",
              "kind"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "layer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Layer UUID or unique exact name. Never inferred from UI selection."
              },
              "seed": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": -32768,
                  "maximum": 32767
                },
                "minItems": 3,
                "maxItems": 3
              },
              "slot": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 256
                  },
                  {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                ],
                "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
              },
              "region": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32768,
                      "maximum": 32767
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "max": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32767,
                      "maximum": 32768
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "min",
                  "max"
                ],
                "additionalProperties": false,
                "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
              },
              "cap": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1048576
              },
              "mirror": {
                "type": "object",
                "properties": {
                  "axes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "y",
                        "z"
                      ]
                    },
                    "minItems": 0,
                    "maxItems": 3,
                    "uniqueItems": true
                  },
                  "plane2": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -65536,
                      "maximum": 65536
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "axes",
                  "plane2"
                ],
                "additionalProperties": false
              },
              "kind": {
                "const": "fill"
              }
            },
            "required": [
              "layer",
              "seed",
              "slot",
              "kind"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "layer": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
                "description": "Layer UUID or unique exact name. Never inferred from UI selection."
              },
              "region": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32768,
                      "maximum": 32767
                    },
                    "minItems": 3,
                    "maxItems": 3
                  },
                  "max": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -32767,
                      "maximum": 32768
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "min",
                  "max"
                ],
                "additionalProperties": false,
                "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
              },
              "slot": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 256
                  },
                  {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                ],
                "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
              },
              "hollow": {
                "type": "boolean"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "place",
                  "paint",
                  "erase"
                ]
              },
              "mirror": {
                "type": "object",
                "properties": {
                  "axes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "y",
                        "z"
                      ]
                    },
                    "minItems": 0,
                    "maxItems": 3,
                    "uniqueItems": true
                  },
                  "plane2": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": -65536,
                      "maximum": 65536
                    },
                    "minItems": 3,
                    "maxItems": 3
                  }
                },
                "required": [
                  "axes",
                  "plane2"
                ],
                "additionalProperties": false
              },
              "kind": {
                "const": "box"
              }
            },
            "required": [
              "layer",
              "region",
              "kind"
            ],
            "additionalProperties": false,
            "if": {
              "properties": {
                "mode": {
                  "const": "erase"
                }
              },
              "required": [
                "mode"
              ]
            },
            "then": {
              "not": {
                "required": [
                  "slot"
                ]
              }
            },
            "else": {
              "required": [
                "slot"
              ]
            }
          }
        ]
      },
      "minItems": 1,
      "maxItems": 256
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "operations"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_box

Build an integer half-open solid box or one-cell shell (hollow=true). Default mode=place, hollow=false, mirror=none. slot required for place/paint, forbidden for erase. One atomic undo entry.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `region`            | Yes      | object. Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime.        |
| `slot`              | Optional | See schema. Stable slot number or unique swatch name; zero is air for explicit writes only.                                          |
| `hollow`            | Optional | boolean                                                                                                                              |
| `mode`              | Optional | string; enum: \["place","paint","erase"\]                                                                                            |
| `mirror`            | Optional | object                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "region": {
      "type": "object",
      "properties": {
        "min": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32768,
            "maximum": 32767
          },
          "minItems": 3,
          "maxItems": 3
        },
        "max": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32767,
            "maximum": 32768
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
    },
    "slot": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 256
        },
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      ],
      "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
    },
    "hollow": {
      "type": "boolean"
    },
    "mode": {
      "type": "string",
      "enum": [
        "place",
        "paint",
        "erase"
      ]
    },
    "mirror": {
      "type": "object",
      "properties": {
        "axes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "x",
              "y",
              "z"
            ]
          },
          "minItems": 0,
          "maxItems": 3,
          "uniqueItems": true
        },
        "plane2": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -65536,
            "maximum": 65536
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "axes",
        "plane2"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "region"
  ],
  "additionalProperties": false,
  "if": {
    "properties": {
      "mode": {
        "const": "erase"
      }
    },
    "required": [
      "mode"
    ]
  },
  "then": {
    "not": {
      "required": [
        "slot"
      ]
    }
  },
  "else": {
    "required": [
      "slot"
    ]
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_erase\_region

Erase occupied cells in min-inclusive/max-exclusive region. Mirror is explicit per call; omitted means none. Invalid/hidden/locked targets reject without partial edits.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `region`            | Yes      | object. Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime.        |
| `mirror`            | Optional | object                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "region": {
      "type": "object",
      "properties": {
        "min": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32768,
            "maximum": 32767
          },
          "minItems": 3,
          "maxItems": 3
        },
        "max": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32767,
            "maximum": 32768
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
    },
    "mirror": {
      "type": "object",
      "properties": {
        "axes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "x",
              "y",
              "z"
            ]
          },
          "minItems": 0,
          "maxItems": 3,
          "uniqueItems": true
        },
        "plane2": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -65536,
            "maximum": 65536
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "axes",
        "plane2"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "region"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_fill

Six-connected flood fill of the seed's slot, including air. Region defaults to document bounds; cap defaults to 1,048,576 visited cells. Cap exhaustion rejects atomically. Mirror never inherits UI state.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `seed`              | Yes      | array; minItems: 3; maxItems: 3                                                                                                      |
| `slot`              | Yes      | See schema. Stable slot number or unique swatch name; zero is air for explicit writes only.                                          |
| `region`            | Optional | object. Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime.        |
| `cap`               | Optional | integer; minimum: 1; maximum: 1048576                                                                                                |
| `mirror`            | Optional | object                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "seed": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": -32768,
        "maximum": 32767
      },
      "minItems": 3,
      "maxItems": 3
    },
    "slot": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 256
        },
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      ],
      "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
    },
    "region": {
      "type": "object",
      "properties": {
        "min": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32768,
            "maximum": 32767
          },
          "minItems": 3,
          "maxItems": 3
        },
        "max": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -32767,
            "maximum": 32768
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
    },
    "cap": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1048576
    },
    "mirror": {
      "type": "object",
      "properties": {
        "axes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "x",
              "y",
              "z"
            ]
          },
          "minItems": 0,
          "maxItems": 3,
          "uniqueItems": true
        },
        "plane2": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -65536,
            "maximum": 65536
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "axes",
        "plane2"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "seed",
    "slot"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_get

Read explicit integer coordinates on one layer, including air as slot 0. Returns values in request order. Out-of-bounds coordinates reject the entire read.

| Argument    | Required | Type / constraints                                                                         |
| ----------- | -------- | ------------------------------------------------------------------------------------------ |
| `model_id`  | Yes      | string                                                                                     |
| `revision`  | Optional | string. Captured monotonic revision, encoded as a decimal u64 string.                      |
| `layer`     | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection. |
| `positions` | Yes      | array; minItems: 1; maxItems: 10000                                                        |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "positions": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "integer",
          "minimum": -32768,
          "maximum": 32767
        },
        "minItems": 3,
        "maxItems": 3
      },
      "minItems": 1,
      "maxItems": 10000
    }
  },
  "required": [
    "model_id",
    "layer",
    "positions"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "layer_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "voxels": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "at": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": -32768,
                  "maximum": 32767
                },
                "minItems": 3,
                "maxItems": 3
              },
              "slot": {
                "type": "integer",
                "minimum": 0,
                "maximum": 256
              }
            },
            "required": [
              "at",
              "slot"
            ],
            "additionalProperties": true
          },
          "minItems": 1,
          "maxItems": 10000
        }
      },
      "required": [
        "model_id",
        "revision",
        "layer_id",
        "voxels"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

### quantum\_voxels\_set

Atomically place or paint explicit cells, at most 65,536. Slot 0 erases; paint affects occupied cells only. Last duplicate wins before mirror expansion; mirror conflicts reject. Omitted mode=place, mirror=none. One undo entry.

| Argument            | Required | Type / constraints                                                                                                                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `expected_epoch`    | Yes      | string                                                                                                                               |
| `operation_id`      | Yes      | string                                                                                                                               |
| `model_id`          | Yes      | string                                                                                                                               |
| `expected_revision` | Yes      | string. Captured monotonic revision, encoded as a decimal u64 string.                                                                |
| `label`             | Optional | string; maxLength: 80. Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime. |
| `layer`             | Yes      | string; maxLength: 128. Layer UUID or unique exact name. Never inferred from UI selection.                                           |
| `voxels`            | Yes      | array; minItems: 1; maxItems: 65536                                                                                                  |
| `mode`              | Optional | string; enum: \["place","paint"\]                                                                                                    |
| `mirror`            | Optional | object                                                                                                                               |

Complete input schema

```json
{
  "type": "object",
  "properties": {
    "expected_epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "model_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,19})$",
      "description": "Captured monotonic revision, encoded as a decimal u64 string."
    },
    "label": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Nonempty text, at most 80 UTF-8 bytes, without control characters. The byte limit is also checked at runtime."
    },
    "layer": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Layer UUID or unique exact name. Never inferred from UI selection."
    },
    "voxels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": -32768,
              "maximum": 32767
            },
            "minItems": 3,
            "maxItems": 3
          },
          "slot": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0,
                "maximum": 256
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            ],
            "description": "Stable slot number or unique swatch name; zero is air for explicit writes only."
          }
        },
        "required": [
          "at",
          "slot"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 65536
    },
    "mode": {
      "type": "string",
      "enum": [
        "place",
        "paint"
      ]
    },
    "mirror": {
      "type": "object",
      "properties": {
        "axes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "x",
              "y",
              "z"
            ]
          },
          "minItems": 0,
          "maxItems": 3,
          "uniqueItems": true
        },
        "plane2": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -65536,
            "maximum": 65536
          },
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": [
        "axes",
        "plane2"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "expected_epoch",
    "operation_id",
    "model_id",
    "expected_revision",
    "layer",
    "voxels"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

Complete output schema

```json
{
  "type": "object",
  "properties": {
    "api_version": {
      "const": "voxelite.v1"
    },
    "session_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "epoch": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ok": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        },
        "operation_id": {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "undo_entry_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "head_id": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_voxels": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "added": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "removed": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "recolored": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "changed_bounds": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "min": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32768,
                    "maximum": 32767
                  },
                  "minItems": 3,
                  "maxItems": 3
                },
                "max": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -32767,
                    "maximum": 32768
                  },
                  "minItems": 3,
                  "maxItems": 3
                }
              },
              "required": [
                "min",
                "max"
              ],
              "additionalProperties": true,
              "description": "Integer region: min inclusive, max exclusive. Each extent must be positive and at most 256 cells; checked at runtime."
            },
            {
              "type": "null"
            }
          ]
        },
        "changed_layers": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "minItems": 0,
          "maxItems": 64
        },
        "palette_changed": {
          "type": "boolean"
        },
        "metadata_changed": {
          "type": "boolean"
        },
        "work_units": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9223372036854775807
        },
        "durability": {
          "const": "memory"
        }
      },
      "required": [
        "model_id",
        "revision",
        "operation_id",
        "undo_entry_id",
        "head_id",
        "changed_voxels",
        "added",
        "removed",
        "recolored",
        "changed_bounds",
        "changed_layers",
        "palette_changed",
        "metadata_changed",
        "work_units",
        "durability"
      ],
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "retryable": {
          "type": "boolean"
        },
        "recovery": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "path": {
          "type": "string"
        },
        "command_index": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255
        },
        "current_revision": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]{0,19})$",
          "description": "Captured monotonic revision, encoded as a decimal u64 string."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "recovery"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "api_version",
    "session_id",
    "epoch",
    "ok"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ],
      "not": {
        "required": [
          "error"
        ]
      }
    },
    {
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ],
      "not": {
        "required": [
          "data"
        ]
      }
    }
  ]
}
```

---

Source: [https://quantum.worldwidewebb.co/docs/format.md](https://quantum.worldwidewebb.co/docs/format.md)

# The .voxl format

One project. One readable JSON file.

`.voxl` stores a complete portable project as UTF-8 JSON. This reference follows `quantum-format` and the validated core model in this development build. Media type: `application/vnd.voxelite.project+json`. Current writer version: `{"major": 1, "minor": 0}`.

## Top-level structure

| Field               | Contract                                                                                                                |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `format`            | Required literal `"quantum"`.                                                                                           |
| `version`           | Required `major` and `minor` unsigned 16-bit integers. Major must be 1. A newer minor is preserved.                     |
| `required_features` | Required array of strings. Only an empty array is currently supported.                                                  |
| `document`          | Required `id`, `name`, `bounds`.                                                                                        |
| `palette`           | Required `slots` and `order`.                                                                                           |
| `layers`            | Required array, bottom to top; 1 to 64 entries.                                                                         |
| `comments`          | Optional thread array, omitted when empty.                                                                              |
| `versions`          | Optional named snapshot array, omitted when empty.                                                                      |
| `lineage`           | Optional source `document` and `version` UUIDs for an independent branch.                                               |
| `extensions`        | Optional plugin ID → section name map; each section has `schema_version`, `encoding` and `payload`. Omitted when empty. |
| `view`              | Optional portable view metadata, excluded from the project semantic hash.                                               |

## Coordinates and layers

Coordinates are integer `[x, y, z]` triples in a right-handed, Y-up space. A cell at `[x,y,z]` occupies a unit cube. `bounds.min` is inclusive and `bounds.max` exclusive. Each extent must be 1 to 256; cell coordinates must lie in `[-32768, 32768)`. The exclusive maximum may equal 32768.

Each layer has `id`, `name`, `visible`, `locked`, and `voxels`. A voxel row is `[x, y, z, slot]`. Omit air entirely: slot zero is invalid on disk. All rows must lie in the document bounds and reference existing palette slots. Duplicate coordinates within a layer reject; the same coordinate in different layers is valid. The highest visible occupied layer wins the composite. Hidden geometry is retained; lock state does not change rendering.

## Palette identity

A slot has `index` (1 to 256), `rgba` (four bytes, alpha exactly 255), and an optional `name`. There must be 1 to 256 slots, with unique indices. `order` is a full permutation of those indices and controls display order independently of identity. No translucent voxels are supported.

## Canonical bytes and hashes

*   Object keys sort lexicographically. Output uses two-space indentation, LF newlines, and one final newline, except raw plugin section envelopes described below.
*   Each voxel occupies one compact line, e.g. `[0, 0, 0, 1]`. Rows sort lexicographically by X, then Y, then Z.
*   Palette slots sort by index; comments and named versions sort by UUID. Layer order, palette display order and message order are meaningful and preserved.
*   UUIDs in validated ID fields use lowercase, hyphenated strings. Names are nonempty, at most 128 UTF-8 bytes, without control characters.
*   Outside `view` and plugin section envelopes, numbers must use integer representation; fractional/exponent/negative-zero representations reject. Finite floating-point values are permitted inside `view` and plugin section envelopes.
*   `Project::semantic_hash()` is SHA-256 of canonical file bytes with top-level `view` and `build_history` removed. Unknown optional metadata and exact extension section bytes remain in that hash.

The project semantic hash differs from a named version's `content_hash`, which hashes the canonical core snapshot serialization. Use the Rust API to compute these hashes; do not substitute a generic pretty-printed JSON hash.

## Comments and named versions

A comment contains `id`, `anchor`, optional `layer`, `resolved`, and ordered `messages`. Anchors are `{"kind":"voxel","at":[x,y,z]}` or `{"kind":"region","min":[x,y,z],"max":[x,y,z]}`. Each message has `id`, `origin` (`human` or `agent`), plain-text `text`, and optional public `tool` ID. Hidden/orphaned state is derived, not stored; an anchor survives deleted geometry.

A named version contains `id`, `name`, optional `parent`, `origin`, `content_hash`, and a nonrecursive `snapshot`. Snapshots contain `name`, `bounds`, `palette`, `layers`, and optional `comments`. Hashes must match. Parents must exist in the same library, and cycles reject. Session IDs, revision counters, undo/redo entries and retry receipts are not serialized by the writer.

## Parser and resource limits

| Resource                                       | Limit                                                                                  |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| Encoded file                                   | 128 MiB                                                                                |
| Live layer-voxels / allocated chunks           | 1,048,576 / 8,192; overlapping layers count separately                                 |
| Decoded voxels across live and version content | 4,194,304                                                                              |
| Metadata excluding voxel arrays                | 8 MiB total; 4 MiB top-level comments, 4 MiB other metadata                            |
| JSON nesting / optional metadata nesting       | 32 / 16                                                                                |
| Comment threads / messages                     | 1,024 / 10,000 per snapshot; each message 1 to 8,192 UTF-8 bytes; 4 MiB comment budget |
| Named versions                                 | 64; aggregate canonical snapshot bytes ≤64 MiB                                         |

Duplicate object keys reject at every level. Parsing validates all layers and snapshots, including hidden content. Unknown major versions and nonempty required-feature lists fail without installing the document. Limits may reject a file before any model becomes available.

## Forward compatibility

Bounded unknown optional fields are preserved as inert data and merged by stable IDs or palette indices, not array position. Generic optional values accept strings, booleans, null, signed 64-bit integers, arrays and objects within depth limits. They are never interpreted as executable code or remote resources. Known fields always come from current validated content.

## Plugin extension data

`extensions[plugin_id][section_name]` stores an envelope with a positive 32-bit `schema_version`, `encoding` (`json` or `bytes`), and required `payload`. JSON payloads may contain any bounded JSON value, including finite fractional numbers. Byte payloads use arrays of integer octets, 0–255.

```json
"extensions": {
  "dev.quantum.example": {
    "state": {"schema_version": 2, "encoding": "json", "payload": {"scale": 1.25}},
    "cache": {"schema_version": 1, "encoding": "bytes", "payload": [0, 255, 128]}
  }
}
```

Plugin IDs follow the lowercase reverse-DNS grammar (2+ labels, 1–63 bytes per label, 253 bytes total). Section names are plugin-local, at most 253 bytes, with dot-separated segments matching `[a-z][a-z0-9_-]*`. Raw envelopes, from opening to closing brace, retain their exact whitespace, key order, escapes and number spelling. Namespace keys sort and use compact JSON. Unknown owners, disabled plugins and undeclared sections remain opaque, including unknown envelope fields.

The namespace shares the existing 4 MiB non-comment metadata budget, counting raw whitespace and envelopes. Section nesting is at most 28 below its root, within the file's 32-level limit. Duplicate keys, malformed envelopes, invalid byte arrays and excessive size/depth reject with a section path. The previous editor and original file remain intact if an open fails.

Enabled owners declare their schema versions and forward migration callbacks. The host stages migrations and validation through `DataCx`, which reads/writes only that owner's declared sections. Missing paths, newer stored versions or callback errors reject without modifying the document. Successful changes form one undoable edit and are saved only on a subsequent save.

The format remains 1.0. Old files without extensions load unchanged; an empty namespace is omitted and preserves existing canonical output. Older builds do not guarantee raw-byte retention. Existing core comments and palette data stay in place. Extensions are project data outside named voxel snapshots; runtime history and build-recipe replay preserve them. See [Plugins](https://quantum.worldwidewebb.co/docs/plugins/#data) for declarations, lifecycle and host integration.

## A complete example

[Download a valid one-voxel project](https://quantum.worldwidewebb.co/assets/minimal.voxl). The site crate tests this fixture against the actual format reader and verifies canonical byte equality.

```json
{
  "document": {
    "bounds": {"max": [16, 16, 16], "min": [0, 0, 0]},
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "One voxel"
  },
  "format": "voxelite",
  "layers": [{
    "id": "00000000-0000-4000-8000-000000000002",
    "locked": false, "name": "Base", "visible": true,
    "voxels": [[0, 0, 0, 1]]
  }],
  "palette": {
    "order": [1],
    "slots": [{"index": 1, "name": "clay", "rgba": [180, 140, 100, 255]}]
  },
  "required_features": [],
  "version": {"major": 1, "minor": 0}
}
```

This displayed example is compacted for readability. The downloadable file uses canonical whitespace. Open it in the editor or with `quantum_document_open` to validate it; the app preserves the existing document if an open fails.

---

Source: [https://quantum.worldwidewebb.co/docs/skills.md](https://quantum.worldwidewebb.co/docs/skills.md)

# Agent skills

Teach the workflow once. Keep the creative loop moving.

These portable skills teach agents how to use the implemented Quantum MCP tools. They cover atomic edits, palette choices, primitive composition, real image inspection and recovery from conflicts.

## Install MCP

[Install Quantum for Mac](https://quantum.worldwidewebb.co/download/) in Applications first. The app includes the MCP server. Open your project folder in your host, then choose an install method below. For [source builds](https://quantum.worldwidewebb.co/docs/getting-started/#build) or a different app location, use the manual configuration with your executable's absolute path.

### Cursor

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=quantum&config=eyJjb21tYW5kIjoiL0FwcGxpY2F0aW9ucy9RdWFudHVtLmFwcC9Db250ZW50cy9NYWNPUy9xdWFudHVtLW1jcCIsImFyZ3MiOlsiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19)

Review and confirm the server in Cursor. The file root is `${workspaceFolder}`, your open project folder. [View mcp.json](https://quantum.worldwidewebb.co/assets/integrations/cursor/mcp.json) for manual setup.

### Claude Code

Run from your project directory; `"$PWD"` sets the file root to that directory.

```sh
claude mcp add quantum -- '/Applications/Quantum.app/Contents/MacOS/quantum-mcp' --root "$PWD"
```

To make the server available across projects, add `--scope user` after `claude mcp add`. Its file root still points to the directory where you ran the command.

### Codex

Run from your project directory; `"$PWD"` sets the file root to that directory.

```sh
codex mcp add quantum -- '/Applications/Quantum.app/Contents/MacOS/quantum-mcp' --root "$PWD"
```

Or merge this into `~/.codex/config.toml` (or your trusted project's `.codex/config.toml`). Replace `<project dir>` with an existing absolute path.

```toml
[mcp_servers.quantum]
command = "/Applications/Quantum.app/Contents/MacOS/quantum-mcp"
args = ["--root","<project dir>"]
```

### VS Code

[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22quantum%22%2C%22command%22%3A%22%2FApplications%2FQuantum.app%2FContents%2FMacOS%2Fquantum-mcp%22%2C%22args%22%3A%5B%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D)

Review and confirm the server in VS Code, or run this CLI command. Both use `${workspaceFolder}` for the file root, resolved by VS Code in your open project.

```sh
code --add-mcp '{"name":"quantum","command":"/Applications/Quantum.app/Contents/MacOS/quantum-mcp","args":["--root","${workspaceFolder}"]}'
```

[View .vscode/mcp.json](https://quantum.worldwidewebb.co/assets/integrations/vscode/mcp.json) for manual setup.

### Other

For Claude Desktop, Windsurf and other MCP hosts, merge this entry into the host's MCP settings. Preserve existing servers and replace `<project dir>` with an existing absolute path.

```json
{
  "mcpServers": {
    "quantum": {
      "command": "/Applications/Quantum.app/Contents/MacOS/quantum-mcp",
      "args": [
        "--root",
        "<project dir>"
      ]
    }
  }
}
```

## Install skills

Install all skills from the repository's `skills/` directory with the open Agent Skills CLI. This installs workflow instructions; configure MCP above to give them tools.

```sh
npx skills add 0x63616c/quantum
```

Add `--skill <name>` for one skill, `-g` for a global install, or `-a claude-code`, `-a cursor` or `-a codex` to pick an agent. [Choose an individual skill](https://quantum.worldwidewebb.co/docs/skills/#available-skills).

For a manual install, [download the skill folders](https://quantum.worldwidewebb.co/assets/quantum-skills.zip) or use a repository checkout. Copy each `skills/<name>/` folder into `.cursor/skills/`, `.claude/skills/`, or `~/.codex/skills/`. [Install, update and removal notes](https://quantum.worldwidewebb.co/assets/skills/README.md).

## What you get

MCP gives your agent voxel editing tools, palettes, real PNG renders, and project save/export. Skills teach it to compose, inspect and refine a model. Each standalone server owns its own session; save `.voxl` files before disconnecting. To edit the live native canvas, [copy the connection configuration from the app](https://quantum.worldwidewebb.co/docs/getting-started/#connect).

## Verify it works

1.  Restart or reconnect your host and list its MCP tools.
2.  Call `quantum_capabilities_get` with `{}`. Expect API `voxelite.v1`, an epoch and available document IDs.
3.  Confirm the installed skills appear in your host, then ask it to use `quantum-workflow` for your first model.

## Choose a skill

### quantum-palettes

Choose, create or apply Quantum palettes with readable material roles and stable slot mappings, without unintended recoloring.

```sh
npx skills add 0x63616c/quantum --skill quantum-palettes
```

[Read skill instructions](https://quantum.worldwidewebb.co/assets/skills/quantum-palettes/SKILL.md)

### quantum-primitives

Build Quantum subjects from integer primitive masses, mirrored boxes and bounded explicit voxel batches for curved shapes.

```sh
npx skills add 0x63616c/quantum --skill quantum-primitives
```

[Read skill instructions](https://quantum.worldwidewebb.co/assets/skills/quantum-primitives/SKILL.md)

### quantum-render-review

Inspect real Quantum MCP renders from multiple angles, identify spatial flaws, and verify repairs at a consistent document revision.

```sh
npx skills add 0x63616c/quantum --skill quantum-render-review
```

[Read skill instructions](https://quantum.worldwidewebb.co/assets/skills/quantum-render-review/SKILL.md)

### quantum-workflow

Create or refine voxel art through Quantum MCP, with atomic edits, visual review, named versions and portable exports.

```sh
npx skills add 0x63616c/quantum --skill quantum-workflow
```

[Read skill instructions](https://quantum.worldwidewebb.co/assets/skills/quantum-workflow/SKILL.md)

## Give it a first brief

> Use the Quantum workflow to build a warm brass lantern within 32 × 32 × 32 cells. Save a blockout version, inspect iso/front/right/back renders, repair the handle silhouette, then save .voxl and GLB.

The render-review skill uses `quantum_render` for real PNG feedback. There is no screenshot-named MCP tool in this build. Primitive guidance also stays within today's catalog: boxes and explicit voxel batches, without invented cylinder or ellipsoid calls.

## Know when it worked

The agent should report the model revision, views it actually inspected, and saved output paths. A successful render call is not visual inspection, and exporting an image is not saving a project. These distinctions are part of every workflow.

---

Source: [https://quantum.worldwidewebb.co/docs/plugins.md](https://quantum.worldwidewebb.co/docs/plugins.md)

# Plugins

Built-in features. One shared core.

Quantum's plugins are statically linked Rust crates shipped with the editor. They declare features through `quantum-plugin-api`; `quantum-plugin-host` validates and enables them. This page describes the implemented boundaries in this development build, including the parts of the plugin architecture still to come.

## What stays in core

The document engine, validation, atomic transactions, undo/redo, native `.voxl` loading and saving, renderer and camera remain core responsibilities. The plugin host and its registry also belong to core. Disabling an optional feature does not remove its existing document content or weaken saving and history guarantees.

The shell owns windows, menus, command search (Cmd-K), settings surfaces and the shortcuts sheet. It derives command labels, icons, menu placement and keybindings from enabled registry contributions. The app still maps command IDs to its `Op` dispatch enum and supplies availability checks; a declaration alone does not implement an action. Settings have declarative schemas, but the existing settings surfaces are still shell adapters. GPUI presentation uses the shared `quantum-ui` components and natural text editing; plugins receive no GPUI context.

## Built-ins in this tree

`app_host()` in `crates/quantum-app/src/core_plugin.rs` registers the required `dev.quantum.core` command provider, followed by these seven optional plugins. Each package lives under `crates/plugins/`.

| Feature    | Implementation and responsibility                                                                                                                                                                                                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tools      | `quantum-plugin-tools` (`dev.quantum.tools`). Place, Erase, Paint, Fill, Box and Picker (eyedropper). Tools return previews and typed command proposals; the host handles picking and the engine admits edits.                                                                                                   |
| Mirror     | `quantum-plugin-mirror` (`dev.quantum.mirror`). Mirror X/Y/Z settings and a command transform applied to pending tool edits before transaction admission. Axes default off.                                                                                                                                      |
| Gizmo/grid | `quantum-plugin-gizmo-grid` (`dev.quantum.gizmo-grid`). Ground grid and camera orientation widget drawing and interaction. The gizmo orbits or snaps the camera; it is not a voxel transform tool.                                                                                                               |
| Palette    | `quantum-plugin-palette` (`dev.quantum.palette`). Presets, local library and palette manager behavior, swatch choices and edit proposals, HEX/GPL/JASC-PAL import, and the PAL exporter. The host handles storage; palette invariants and edit execution stay in core.                                           |
| Comments   | `quantum-plugin-comments` (`dev.quantum.comments`). Discussion panel behavior, placement, filtering, pin overlays and MCP comment requests. Stored comments remain core snapshot content, including history and named versions.                                                                                  |
| Agent/MCP  | `quantum-plugin-agent` (`dev.quantum.agent`). Metadata for the Agent connection and Extensions shell commands. Their execution remains in the app; both have `agent_visible = false`. MCP transport and tool dispatch remain in `quantum-mcp`, with palette, comments and exports using enabled plugin bindings. |
| Exporters  | `quantum-plugin-exporters` (`dev.quantum.exporters`). GLB and PNG byte encoders plus HEX/GPL palette exports. The host supplies snapshots/rendering and writes the output. Native `.voxl` saving remains available when exporters are disabled.                                                                  |

**Shadows, lighting and FPS/stats are not separate plugins yet.** The architecture calls for them to become optional built-ins, but this tree has no such plugin packages or registrations. Shadow and lighting implementation remains in `quantum-render`; viewport frame measurement, statistics display and its preference remain in the app. The agent plugin likewise does not yet own the whole MCP implementation. See [MCP tools](https://quantum.worldwidewebb.co/docs/mcp.md) for the current wire interface.

## Manifests and contribution points

A plugin implements the `Plugin` trait. `Plugin::manifest` returns a `Manifest` with a stable reverse-DNS `PluginId`, `name_key` and `description_key`, implementation `version`, required `api_version`, and the `builtin`, `default_enabled` and `can_disable` flags. `API_VERSION` is currently `0.7.0`; it is independent of plugin versions, the `.voxl` format version and section schema versions.

A contribution point is a supported kind of declaration the host can discover and present or dispatch. `Plugin::contribute` fills a `Registrar` with data-only declarations:

*   `CommandContribution`: command ID, label, JSON argument schema, optional shortcut/context, icon, menu, presentation order and agent visibility.
*   `ToolContribution` and `CommandTransformContribution`: interactive tools and ordered rewrites of pending commands.
*   `PanelContribution` and `FormatContribution`: host-rendered panels and import/export format metadata.
*   `RenderPassContribution`: a declared insertion slot, `BeforeScene`, `AfterScene` or `Overlay`; no renderer resources are handed to the plugin.
*   `SettingContribution`: a namespaced Bool, Choice or Number schema and typed default.
*   `DataSectionContribution`: a plugin-local section name and positive schema version for project data.

Declarations do not automatically supply behavior. Bind implemented features with `Plugin::tool`, `command_transform`, `overlay`, `palette_panel`, `comments_panel` or `exporter`. Host-provided contexts such as `ToolCx`, `PaletteCx`, `CommentsCx`, `DataCx` and `ExportCx` expose only the relevant queries or proposals. Plugins do not receive the engine, app or an unrestricted service locator. `CommandCx` and `ActivateCx` are currently stubs.

## Enablement and lifecycle

The seven optional built-ins ship with `builtin = true`, `default_enabled = true` and `can_disable = true`. The host can disable them with `Host::disable` and re-enable them with `Host::enable`. The required `dev.quantum.core` provider has `can_disable = false`. There is no plugin enablement preferences UI yet.

`Host::new` uses manifest defaults. `Host::with_enabled` accepts an explicit `EnabledSet` instead, while still selecting required plugins. Registration validates manifests, API compatibility and declarations. Enablement checks contribution-ID and default-keybinding conflicts before calling `activate`; a conflict leaves the candidate disabled. `Registry` exposes only successfully enabled declarations. Disabling calls `deactivate` and removes those declarations from the live registry; repeated requests for the same state are no-ops.

Lifecycle hooks and feature callbacks run behind `catch_unwind`. A panic in contribution, lifecycle or feature callbacks faults the plugin, removes its declarations and prevents retries for that host's lifetime. A panic while reading the manifest rejects registration because identity has not been established. `HostEvent` reports faults and transitions; `Timings` records callback costs and advisory budget overruns. Ordinary callback errors return to the caller without automatically faulting the plugin.

Panic isolation requires unwinding: it cannot recover from an abort or roll back arbitrary external effects performed by plugin code. This is an in-process API boundary, not a sandbox. Hosts stage document proposals and plugin data before committing them through core validation.

## The dependency rule

Plugin packages may depend on `quantum-plugin-api` and external crates in normal and build dependencies. Every other workspace crate is forbidden there, including `quantum-core`, `quantum-app`, `quantum-render` and `quantum-ui`. The rule also covers optional, renamed and target-specific dependencies. Shared core types and export encoders are exposed through the API crate.

Dev-dependencies are exempt so tests can use `quantum_plugin_host::conformance::check`. `cargo xtask check plugin-deps` enforces the boundary from Cargo metadata.

## Versioned project data

A plugin may declare `DataSectionContribution { section_name, schema_version }` and store data at `extensions[plugin_id][section_name]` in `.voxl`. Each section envelope contains a positive `schema_version`, an `encoding` of `json` or `bytes`, and a `payload`. `DataCx` can read or write only the enabled owner's declared sections.

`Host::load_data` stages forward `DataMigration` callbacks and `Plugin::load_data` validation for enabled owners. Missing migration paths, newer stored schemas and callback errors reject the operation without changing the engine; panics also fault the owner. Successful changes commit together as one undoable edit. Hosts must run this load step when re-enabling a plugin against an open document too.

Unknown owners, disabled plugins and undeclared sections retain their raw envelope bytes, including whitespace and key order. Current sections retain their bytes unless changed. The format remains 1.0, and empty extensions are omitted. Existing palette and comment data stay in their core fields; they have not been migrated into extensions. See [plugin extension data in the .voxl format](https://quantum.worldwidewebb.co/docs/format/#plugin-data) for the wire example, limits and preservation rules.

## Write a built-in plugin

Start with `crates/plugins/quantum-plugin-example`. Its `ExamplePlugin` uses ID `dev.quantum.example` and declares one `CommandContribution`, `dev.quantum.example.command`, with an empty-object argument schema. It implements no feature or command execution, has `builtin = false` and `default_enabled = false`, and is not linked into the app.

1.  **Check the template.** Read its `Cargo.toml` and `src/lib.rs`, then run the commands below from the repository root.
2.  **Create a package under `crates/plugins/`.** Copy the example into a new directory, choose a unique package name and reverse-DNS plugin ID, and update contribution IDs and label keys. The workspace already includes `crates/plugins/*`. Keep `quantum-plugin-api` as the only workspace dependency outside tests.
3.  **Declare and bind the feature.** Implement `manifest` and `contribute`, then the relevant behavior lookup. Return typed proposals through the API; leave transaction admission, file I/O and GPUI presentation to the host. For an optional shipped built-in, set `builtin`, `default_enabled` and `can_disable` to `true`.
4.  **Test the contract and behavior.** Keep the example's conformance test, replacing `ExamplePlugin` with your type. Add feature tests for errors, disable/re-enable behavior and unchanged core document guarantees. Use the dependency checker to catch accidental workspace coupling.
5.  **Wire it into the app.** Add the new package to `crates/quantum-app/Cargo.toml` and its instance to `app_host()`. For shell commands, extend the `Op` ID mapping in `crates/quantum-app/src/actions.rs` and the app's execution/availability adapters. A new panel or capability also needs its shell adapter. Rebuild and test the app; merely adding a crate or declaration does not make it a working feature.

```sh
cargo test --locked -p quantum-plugin-example
cargo xtask check plugin-deps
cargo test -p xtask --locked checks::plugin_deps
```

The example's conformance test is:

```rust
#[test]
fn conforms_to_plugin_contract() {
    quantum_plugin_host::conformance::check(|| Box::new(ExamplePlugin));
}
```

The harness checks declarations and exercises an enable/disable/enable cycle, including implementation availability for supported bindings. It complements feature-specific tests; it does not supply missing command execution.

## What is not supported yet

There is no third-party plugin loading, dynamic library loading, scripting API or plugin marketplace. The Rust API is not a stable binary ABI. Built-in plugins are developed and reviewed as part of this repository and linked at build time.