ultravisor 1.0.8 → 1.0.9

package/docs/_sidebar.md

@@ -10,6 +10,10 @@
   - [Capabilities](features/capabilities.md)
   - [Beacons](features/beacons.md)
   - [Building Beacon Providers](features/beacon-providers.md)
+  - [Beacon Authentication](features/beacon-authentication.md)
+  - [Universal Addressing](features/universal-addressing.md)
+  - [Reachability Matrix](features/reachability-matrix.md)
+  - [Platform Cards](features/platform-cards.md)
   - [LLM Integration](features/llm.md)
   - [LLM Model Setup Guide](features/llm-model-setup.md)
   - [Operations](features/operations.md)
@@ -33,3 +37,7 @@
   - [API Server](features/api.md)
   - [CLI Commands](features/cli.md)
   - [Configuration](features/configuration.md)
+
+- Case Studies
+
+  - [retold-remote + orator-conversion](features/case-study-retold-remote.md)

package/docs/features/api.md

@@ -210,6 +210,148 @@ Returns an array of all operation manifests from the current session.
 }
 ```
 
+### Beacons
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/Beacon/Register` | Register a new Beacon worker |
+| `GET` | `/Beacon` | List all registered Beacons |
+| `GET` | `/Beacon/:BeaconID` | Get a specific Beacon |
+| `DELETE` | `/Beacon/:BeaconID` | Deregister a Beacon |
+| `POST` | `/Beacon/:BeaconID/Heartbeat` | Send a Beacon heartbeat |
+| `POST` | `/Beacon/Work/Poll` | Poll for available work |
+| `POST` | `/Beacon/Work/:WorkItemHash/Complete` | Report work item completion |
+| `POST` | `/Beacon/Work/:WorkItemHash/Error` | Report work item failure |
+| `POST` | `/Beacon/Work/:WorkItemHash/Progress` | Report work item progress |
+| `POST` | `/Beacon/Work/:WorkItemHash/Upload` | Upload a binary result file for a work item |
+| `GET` | `/Beacon/Work` | List all work items |
+| `GET` | `/Beacon/Affinity` | List active affinity bindings |
+| `GET` | `/Beacon/Reachability` | Get the connectivity matrix between all beacon pairs |
+| `POST` | `/Beacon/Reachability/Probe` | Trigger connectivity probes between all online beacon pairs |
+
+#### POST /Beacon/Register
+
+Register a new Beacon worker with the coordinator.
+
+```bash
+curl -X POST http://localhost:54321/Beacon/Register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "Name": "GPU-Worker-1",
+    "Capabilities": ["Shell", "FileSystem"],
+    "MaxConcurrent": 4
+  }'
+```
+
+Response:
+
+```json
+{
+    "BeaconID": "beacon-abc123",
+    "Name": "GPU-Worker-1",
+    "Capabilities": ["Shell", "FileSystem"],
+    "MaxConcurrent": 4,
+    "Status": "Online"
+}
+```
+
+#### POST /Beacon/Work/Poll
+
+Poll for available work matching the Beacon's capabilities.
+
+```bash
+curl -X POST http://localhost:54321/Beacon/Work/Poll \
+  -H "Content-Type: application/json" \
+  -d '{ "BeaconID": "beacon-abc123" }'
+```
+
+Response:
+
+```json
+{
+    "WorkItem": {
+        "WorkItemHash": "wi-xyz789",
+        "Capability": "Shell",
+        "Action": "Execute",
+        "Settings": { "Command": "echo hello" }
+    }
+}
+```
+
+#### POST /Beacon/Work/:WorkItemHash/Complete
+
+Report successful completion of a work item.
+
+```bash
+curl -X POST http://localhost:54321/Beacon/Work/wi-xyz789/Complete \
+  -H "Content-Type: application/json" \
+  -d '{
+    "Outputs": { "StdOut": "hello\n", "ExitCode": 0 },
+    "Log": ["Command executed successfully"]
+  }'
+```
+
+#### POST /Beacon/Work/:WorkItemHash/Upload
+
+Upload a binary result file for a work item. The Beacon sends raw file
+bytes with `Content-Type: application/octet-stream` and an
+`X-Output-Filename` header. The file is written to the operation's
+staging directory. Requires session auth.
+
+```bash
+curl -X POST http://localhost:54321/Beacon/Work/wi-xyz789/Upload \
+  -H "Content-Type: application/octet-stream" \
+  -H "X-Output-Filename: result.bin" \
+  --data-binary @result.bin
+```
+
+Response:
+
+```json
+{
+    "Status": "Uploaded",
+    "WorkItemHash": "wi-xyz789",
+    "FilePath": "/data/staging/my-pipeline/result.bin"
+}
+```
+
+#### GET /Beacon/Reachability
+
+Returns the connectivity matrix between all beacon pairs. No auth
+required (management UI).
+
+```bash
+curl http://localhost:54321/Beacon/Reachability
+```
+
+Response:
+
+```json
+[
+    {
+        "SourceBeaconID": "beacon-abc123",
+        "TargetBeaconID": "beacon-def456",
+        "Status": "Reachable",
+        "ProbeLatencyMs": 12,
+        "LastProbeAt": "2026-03-21T10:00:00.000Z",
+        "ProbeURL": "http://192.168.1.10:54322/probe"
+    }
+]
+```
+
+#### POST /Beacon/Reachability/Probe
+
+Triggers connectivity probes between all online beacon pairs. Returns
+the updated reachability matrix after probes complete. No auth required
+(management UI).
+
+```bash
+curl -X POST http://localhost:54321/Beacon/Reachability/Probe
+```
+
+Response: Array of reachability records (same shape as
+`GET /Beacon/Reachability`).
+
 ## Error Responses
 
 All error responses follow this format:

package/docs/features/beacons.md

@@ -121,6 +121,7 @@ Register a new Beacon worker with the coordinator.
 | `Capabilities` | array | yes | List of capability strings |
 | `MaxConcurrent` | number | no | Maximum concurrent work items (default: 1) |
 | `Tags` | object | no | Arbitrary key-value metadata |
+| `BindAddresses` | array | no | Network interfaces the Beacon is listening on. Each entry is `{ IP, Port, Protocol }`. Used by the reachability service to probe connectivity between Beacons. |
 
 **Response:** The created Beacon record including the assigned `BeaconID`.
 
@@ -224,6 +225,57 @@ List all active affinity bindings.
 **Response:** Array of affinity binding records, each containing
 `AffinityKey`, `BeaconID`, `CreatedAt`, and `ExpiresAt`.
 
+---
+
+### GET /Beacon/Reachability
+
+Returns the connectivity matrix between all beacon pairs. No auth
+required (management UI).
+
+**Response:** Array of reachability records:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `SourceBeaconID` | string | Beacon that initiated the probe |
+| `TargetBeaconID` | string | Beacon that was probed |
+| `Status` | string | Connectivity status (e.g. `Reachable`, `Unreachable`) |
+| `ProbeLatencyMs` | number | Round-trip latency of the probe in milliseconds |
+| `LastProbeAt` | string | ISO timestamp of the last probe |
+| `ProbeURL` | string | URL that was probed |
+
+---
+
+### POST /Beacon/Reachability/Probe
+
+Triggers connectivity probes between all online beacon pairs. Returns
+the updated reachability matrix after probes complete. No auth required
+(management UI).
+
+**Response:** Array of reachability records (same shape as
+`GET /Beacon/Reachability`).
+
+---
+
+### POST /Beacon/Work/:WorkItemHash/Upload
+
+Uploads a binary result file for a work item. The Beacon sends raw file
+bytes with `Content-Type: application/octet-stream` and an
+`X-Output-Filename` header specifying the file name. The file is written
+to the operation's staging directory.
+
+Requires session auth.
+
+**Request headers:**
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Content-Type` | yes | Must be `application/octet-stream` |
+| `X-Output-Filename` | yes | Target file name for the uploaded file |
+
+**Request body:** Raw binary file bytes.
+
+**Response:** `{ Status: "Uploaded", WorkItemHash: "...", FilePath: "..." }`
+
 ## Custom Capability Providers
 
 Beacons use a pluggable **CapabilityProvider** system. Each provider handles

package/docs/features/case-study-retold-remote.md

@@ -0,0 +1,223 @@
+# Case Study: retold-remote + orator-conversion
+
+This case study shows how retold-remote (a media browser) and orator-conversion (a media processing worker) integrate through Ultravisor's operation pipeline to generate thumbnails, previews, waveforms, and other derived media artifacts.
+
+## System Overview
+
+```mermaid
+graph TB
+    subgraph "retold-remote (NAS)"
+        RR[retold-remote server]
+        FS[(Media Files<br/>/Users/steven)]
+        RR --- FS
+    end
+
+    subgraph "Ultravisor (Coordinator)"
+        UV[Ultravisor API Server]
+        OPS[(Operation Graphs)]
+        RM[Reachability Matrix]
+        UV --- OPS
+        UV --- RM
+    end
+
+    subgraph "orator-conversion (Worker)"
+        OC[orator-conversion beacon]
+        SHARP[Sharp / ffmpeg / pdftoppm]
+        OC --- SHARP
+    end
+
+    RR -->|"triggerOperation('rr-image-thumbnail', params)"| UV
+    UV -->|"Enqueue MediaConversion/ImageResize"| OC
+    OC -->|"Upload result binary"| UV
+    UV -->|"Stream binary response"| RR
+```
+
+## How It Connects
+
+### 1. Startup
+
+All three services start independently:
+
+```bash
+# Terminal 1: Ultravisor
+ultravisor start -l
+
+# Terminal 2: retold-remote
+retold-remote serve ~/Media -u -l
+
+# Terminal 3: orator-conversion
+npm start -- -u -l
+```
+
+### 2. Registration
+
+```mermaid
+sequenceDiagram
+    participant RR as retold-remote
+    participant UV as Ultravisor
+    participant OC as orator-conversion
+
+    OC->>UV: POST /Beacon/Register<br/>{Name: "orator-conversion", Capabilities: ["MediaConversion"],<br/>ActionSchemas: [ImageResize, VideoThumbnail, ...],<br/>BindAddresses: [{IP: "127.0.0.1", Port: 8765}]}
+    UV->>UV: Register beacon, auto-generate 14 task types
+    UV->>UV: Probe reachability (no other beacons yet)
+    UV-->>OC: {BeaconID: "bcn-orator-conversion-..."}
+
+    RR->>UV: WebSocket: BeaconRegister<br/>{Name: "retold-remote", Contexts: {File: {BaseURL: "http://localhost:7827/content/"}},<br/>BindAddresses: [{IP: "127.0.0.1", Port: 7827}],<br/>Operations: [rr-image-thumbnail, rr-video-thumbnail, ...]}
+    UV->>UV: Register beacon, store 9 operation definitions
+    UV->>UV: Probe: retold-remote ↔ orator-conversion = REACHABLE
+
+    Note over UV: Both beacons registered.<br/>14 beacon task types available.<br/>9 operations from retold-remote.<br/>Reachability: all pairs reachable.
+```
+
+### 3. Auto-Generated Operations
+
+retold-remote registers 9 operation definitions during beacon connection. These are complete operation graphs with nodes, connections, and state wiring — built programmatically by `_buildPipelineOperation()`:
+
+| Operation | Trigger Parameters | Pipeline |
+|-----------|-------------------|----------|
+| `rr-image-thumbnail` | ImageAddress, Width, Height, Format, Quality | resolve → transfer → resize → send-result |
+| `rr-video-thumbnail` | VideoAddress, Timestamp, Width | resolve → transfer → extract frame → send-result |
+| `rr-video-frame-extraction` | VideoAddress, Timestamp, Width | resolve → transfer → probe → extract → send-result |
+| `rr-audio-waveform` | AudioAddress, SampleRate, Samples | resolve → transfer → waveform → send-result |
+| `rr-audio-segment` | AudioAddress, Start, Duration, Codec | resolve → transfer → extract → send-result |
+| `rr-pdf-page-render` | PdfAddress, Page, LongSidePixels | resolve → transfer → render → send-result |
+| `rr-image-convert` | ImageAddress, Format, Quality | resolve → transfer → convert → send-result |
+| `rr-ebook-convert` | EbookAddress | resolve → transfer → ebook-convert → send-result |
+| `rr-media-probe` | MediaAddress | resolve → transfer → ffprobe → send-result |
+
+Each pipeline follows the same pattern:
+
+```mermaid
+graph LR
+    S[Start] --> R[resolve-address]
+    R -->|URL, Filename| T[file-transfer]
+    T -->|LocalPath| P[beacon-mediaconversion-*]
+    P -->|OutputFile| SR[send-result]
+    SR --> E[End]
+
+    R -.->|Error| E
+    T -.->|Error| E
+    P -.->|Error| E
+    SR -.->|Error| E
+```
+
+State connections wire outputs from earlier nodes into inputs of later nodes:
+- `resolve.URL` → `transfer.SourceURL`
+- `resolve.Filename` → `transfer.Filename`
+- `transfer.LocalPath` → `process.InputFile`
+
+## End-to-End: Image Thumbnail Generation
+
+When a user navigates to a folder in retold-remote, the browser requests thumbnails. Here's the complete flow:
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant RR as retold-remote
+    participant UV as Ultravisor
+    participant OC as orator-conversion
+
+    Browser->>RR: GET /content/preview/photo.jpg?w=400&h=300
+
+    Note over RR: Check cache → miss
+
+    RR->>UV: POST /Operation/rr-image-thumbnail/Trigger<br/>{Parameters: {ImageAddress: ">retold-remote/File/photo.jpg",<br/>Width: 400, Height: 300, Format: "webp", Quality: 80}}
+
+    Note over UV: Start operation (sync mode)
+
+    UV->>UV: resolve-address<br/>>retold-remote/File/photo.jpg<br/>→ http://localhost:7827/content/photo.jpg
+
+    UV->>RR: HTTP GET http://localhost:7827/content/photo.jpg
+    RR-->>UV: 200 OK (image bytes)
+    UV->>UV: file-transfer saves to staging<br/>/staging/rr-image-thumbnail-.../photo.jpg
+
+    UV->>UV: beacon-mediaconversion-imageresize<br/>enqueue work item, WaitingForInput
+
+    OC->>UV: POST /Beacon/Work/Poll
+    UV-->>OC: WorkItem: {Action: "ImageResize",<br/>Settings: {InputFile: "/.../photo.jpg",<br/>OutputFile: "/.../thumbnail.jpg", Width: 400, ...}}
+
+    OC->>OC: Sharp: resize photo.jpg → thumbnail.jpg
+    OC->>UV: POST /Beacon/Work/{hash}/Upload<br/>(raw binary: thumbnail.jpg)
+    UV->>UV: Write to operation staging
+
+    OC->>UV: POST /Beacon/Work/{hash}/Complete
+    UV->>UV: resumeOperation → send-result<br/>finds thumbnail.jpg in staging
+
+    UV-->>RR: 200 OK<br/>Content-Type: application/octet-stream<br/>Body: (thumbnail bytes)
+
+    RR->>RR: Cache the thumbnail
+    RR-->>Browser: 200 OK (thumbnail image)
+```
+
+### Timing
+
+On localhost, the full round-trip takes ~1-3 seconds:
+
+| Step | Duration |
+|------|----------|
+| Address resolution | < 1ms |
+| File transfer (50MB image) | ~200ms |
+| Sharp resize | ~500ms |
+| Binary upload | ~100ms |
+| Total | ~1s |
+
+### Fallback
+
+If Ultravisor is unreachable or the operation fails, retold-remote falls through to local processing:
+
+```javascript
+this._dispatcher.triggerOperation('rr-image-thumbnail',
+    { ImageAddress: '>retold-remote/File/' + tmpRelPath, Width, Height, Format, Quality },
+    (pTriggerError, pResult) =>
+    {
+        if (!pTriggerError && pResult && pResult.OutputBuffer)
+        {
+            return fCallback(null, pResult.OutputBuffer);
+        }
+        // Fall through to local Sharp/ImageMagick
+        this._generateImageThumbnailLocal(pFullPath, pWidth, pHeight, pFormat, fCallback);
+    });
+```
+
+## Large File Support
+
+orator-conversion handles arbitrarily large images (including 256MB+ scans):
+
+- **File-path mode**: Sharp receives the file path directly instead of loading the entire file into a buffer
+- **No pixel limit**: `sharp(filePath, { limitInputPixels: false })` — disables Sharp's default pixel limit
+- **Streaming**: File transfer uses Node.js streams, avoiding full-file buffering
+- **Binary upload**: Result files transfer as raw bytes over HTTP or WebSocket — no base64 encoding
+
+## Error Handling
+
+When a beacon reports a non-zero exit code (e.g., Sharp can't process a corrupt file), the beacon client reports it as an error. The operation graph's Error event fires, routing to the End node. The trigger returns a JSON response with `Success: false`, and retold-remote falls back to local processing.
+
+```mermaid
+flowchart TD
+    A[Beacon processes work item] --> B{ExitCode == 0?}
+    B -->|Yes| C[Upload output file]
+    C --> D[Report completion]
+    D --> E[Operation resumes → send-result → binary stream]
+    B -->|No| F[Report error]
+    F --> G[Operation resumes → Error event → End node]
+    G --> H[Trigger returns JSON with Success: false]
+    H --> I[retold-remote falls back to local processing]
+```
+
+## Logging
+
+All three services support `-l` for file logging:
+
+```bash
+ultravisor start -l                    # ultravisor-2026-03-21T...log
+retold-remote serve ~/Media -u -l      # retold-remote-2026-03-21T...log
+npm start -- -u -l                     # orator-conversion-2026-03-21T...log
+```
+
+Key log prefixes for tracing the pipeline:
+- `[TriggerOp]` — retold-remote dispatcher
+- `[Trigger]` — Ultravisor trigger endpoint
+- `[Engine]` — Ultravisor execution engine
+- `[Coordinator]` — Beacon coordinator (work queue, uploads)
+- `[OratorConversion]` — orator-conversion provider
+- `[Beacon]` — Beacon client (execution, upload, completion)

package/docs/features/platform-cards.md

@@ -0,0 +1,145 @@
+# Platform Cards & Task Types
+
+Ultravisor's operation graphs are built from cards (task types). Platform cards handle the infrastructure layer — address resolution, file transfer, and result delivery. Extension cards handle beacon dispatch. Beacon cards are auto-generated from registered beacon capabilities.
+
+## Platform Cards
+
+### resolve-address
+
+Resolves a universal address (`>beacon/context/path`) to a concrete URL with optional transfer strategy selection.
+
+See [Universal Addressing](universal-addressing.md) for full details.
+
+### file-transfer
+
+Downloads a file from a URL to the operation's staging directory.
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `SourceURL` | String | Yes | URL to download from |
+| `Filename` | String | Yes | Filename to save as in staging |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `LocalPath` | String | Absolute path to the downloaded file |
+| `BytesTransferred` | Number | File size in bytes |
+| `DurationMs` | Number | Download duration |
+
+Supports HTTP/HTTPS with single-redirect following. 5-minute timeout. Creates staging directory if needed.
+
+### send-result
+
+Marks a staging file as the operation's binary output. The trigger endpoint streams this file directly to the caller.
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `FilePath` | String | Yes | Path to the result file (relative to staging) |
+| `OutputKey` | String | No | Key name for the output (default: `ResultFile`) |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `StagingFilePath` | String | Absolute path to the result file |
+| `BytesSent` | Number | File size in bytes |
+| `DurationMs` | Number | Processing duration |
+
+The trigger endpoint scans all task outputs for `StagingFilePath`. If found and the file exists, it streams the file as `application/octet-stream` with metadata in response headers (`X-Run-Hash`, `X-Status`, `X-Elapsed-Ms`).
+
+### base64-encode / base64-decode
+
+Encode a staging file to a base64 string or decode a base64 string to a staging file. Used for embedding small binary payloads in operation state.
+
+## Extension Cards
+
+### beacon-dispatch
+
+The generic card for dispatching work to beacon workers. Most users won't use this directly — catalog-generated beacon cards provide typed wrappers.
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `RemoteCapability` | String | Yes | Required capability (e.g., `Shell`, `MediaConversion`) |
+| `RemoteAction` | String | No | Specific action within the capability |
+| `Command` | String | No | Shell command for Shell capability |
+| `InputData` | String | No | JSON data with universal addresses (auto-resolved) |
+| `OutputFile` | String | No | Expected output filename (triggers binary upload) |
+| `AffinityKey` | String | No | Sticky routing key |
+| `TimeoutMs` | Number | No | Work item timeout (default: 300000) |
+
+When `OutputFile` is set, the executor:
+1. Sets up a work directory for the output
+2. After processing, collects the output file
+3. Uploads it to Ultravisor's staging directory via HTTP POST or WebSocket binary frame
+4. Reports JSON completion separately
+
+## Auto-Generated Beacon Cards
+
+When a beacon registers with action schemas, Ultravisor auto-generates typed task cards. For example, orator-conversion's `MediaConversion` capability with `ImageResize` action becomes:
+
+**`beacon-mediaconversion-imageresize`**
+
+```mermaid
+flowchart LR
+    A[Action Schema<br/>from beacon registration] --> B[_registerCatalogTaskTypes]
+    B --> C["Task type: beacon-mediaconversion-imageresize<br/>Settings: InputFile, OutputFile, Width, Height, Format, Quality<br/>Execute: beaconDispatch → enqueueWorkItem → WaitingForInput"]
+```
+
+The naming convention is: `beacon-{capability}-{action}` (lowercased, non-alphanumeric replaced with hyphens).
+
+### How Auto-Generation Works
+
+1. Beacon registers with `ActionSchemas` array containing capability, action name, settings schema, and description
+2. Coordinator's `_updateActionCatalog()` stores them persistently
+3. `_registerCatalogTaskTypes()` iterates the catalog and creates a task type config for each entry
+4. Each config gets an `Execute` function via `_createBeaconDispatchExecutor()` that:
+   - Coerces setting types (template-resolved strings → numbers/booleans per schema)
+   - Calls `beaconDispatch()` helper to enqueue the work item
+   - Returns `WaitingForInput` with `ResumeEventName: 'Complete'`
+5. Built-in task types take precedence — catalog types are only registered if no type with the same hash exists
+
+### Current orator-conversion Actions
+
+| Hash | Action | Settings |
+|------|--------|----------|
+| `beacon-mediaconversion-imagejpgtopng` | ImageJpgToPng | InputFile, OutputFile |
+| `beacon-mediaconversion-imagepngtojpg` | ImagePngToJpg | InputFile, OutputFile |
+| `beacon-mediaconversion-imageresize` | ImageResize | InputFile, OutputFile, Width, Height, Format, Quality |
+| `beacon-mediaconversion-imagerotate` | ImageRotate | InputFile, OutputFile, Angle |
+| `beacon-mediaconversion-imageconvert` | ImageConvert | InputFile, OutputFile, Format, Quality |
+| `beacon-mediaconversion-pdfpagetopng` | PdfPageToPng | InputFile, OutputFile, Page |
+| `beacon-mediaconversion-pdfpagetojpg` | PdfPageToJpg | InputFile, OutputFile, Page |
+| `beacon-mediaconversion-pdfpagetopngsized` | PdfPageToPngSized | InputFile, OutputFile, Page, LongSidePixels |
+| `beacon-mediaconversion-pdfpagetojpgsized` | PdfPageToJpgSized | InputFile, OutputFile, Page, LongSidePixels |
+| `beacon-mediaconversion-mediaprobe` | MediaProbe | InputFile |
+| `beacon-mediaconversion-videoextractframe` | VideoExtractFrame | InputFile, OutputFile, Timestamp, Width |
+| `beacon-mediaconversion-videothumbnail` | VideoThumbnail | InputFile, OutputFile, Timestamp, Width |
+| `beacon-mediaconversion-audioextractsegment` | AudioExtractSegment | InputFile, OutputFile, Start, Duration, Codec |
+| `beacon-mediaconversion-audiowaveform` | AudioWaveform | InputFile, SampleRate, Samples |
+
+## Binary Output Return
+
+When a beacon processes a work item that produces a file output, the result is transferred back to Ultravisor's staging directory as raw binary — no base64 encoding.
+
+```mermaid
+sequenceDiagram
+    participant Beacon as Beacon Worker
+    participant Exec as Beacon Executor
+    participant Client as Beacon Client
+    participant UV as Ultravisor
+
+    Beacon->>Exec: execute(workItem)
+    Exec->>Exec: Download source file
+    Exec->>Beacon: provider.execute(action, workItem, context)
+    Beacon-->>Exec: { Outputs: { Result: outputPath }, Log }
+    Exec->>Exec: _collectOutputFiles → set OutputFilePath
+
+    alt HTTP Transport
+        Client->>UV: POST /Beacon/Work/{hash}/Upload<br/>Content-Type: application/octet-stream<br/>X-Output-Filename: thumbnail.jpg<br/>Body: raw bytes
+        UV->>UV: recordResultUpload → write to operation staging
+    else WebSocket Transport
+        Client->>UV: JSON: { Action: "WorkResultUpload", WorkItemHash, OutputFilename, OutputSize }
+        Client->>UV: Binary frame: raw file bytes
+        UV->>UV: recordResultUpload → write to operation staging
+    end
+
+    Client->>UV: JSON completion: { Outputs, Log }
+    UV->>UV: resumeOperation → send-result finds file in staging
+```