@ue-shed/protocol 0.5.0 → 0.6.0

package/contracts/cameras/map-tile/v1/README.md

@@ -14,14 +14,28 @@ capture Z does not define detail. The editor renders `gutterPixels` beyond each
 units-per-pixel and crops back to `tilePixelSize` before PNG encoding. Consumers use clamp-to-edge
 sampling inside each published tile.
 
-`captureBackend` is an optional execution hint, not part of the portable plan. Its default
-`scene_capture_tiles` behavior remains the v1 tile operation. The experimental
-`viewport_high_resolution` value requires one complete zoom level of at most 64 tiles; Unreal
-renders that level through the active Level Editor viewport's High Resolution Screenshot path and
-then cuts the resulting image into the requested tiles.
+`captureBackend` is an optional execution hint, not part of the portable plan. The default is
+`lit_camera_tiles`, requiring `cameras.lit-map-tile-capture.v1` and an unlocked rendering editor
+viewport. It accepts `full_fidelity` with natural LOD. `overviewBounds` supplies the complete run's
+framing for shared exposure calibration; when omitted the first batch's extent is used. Optional
+`capture.render.exposureEV100` pins the camera exposure range instead of calibrating automatically.
+
+Call `BeginMapTileCapture(RequestJson)` to start a batch, then
+`PollMapTileCapture(RunId, OperationId)` until `capture-operation.schema.json` reports `finished`.
+The terminal `response` uses the existing capture-response schema. Polling renews a 120-second
+inactivity lease. A run retains viewport, exposure, and scene-freeze ownership between batches;
+call `EndMapTileCapture(RunId)` in a finalizer on success, failure, and cancellation. End returns
+`{ "released": boolean }`; an unrelated run ID cannot release the owner. Only one batch runs at a
+time, and a run's map and capture policy cannot change between batches.
+
+Explicit `scene_capture_tiles` and `viewport_high_resolution` use the synchronous `CaptureMapTiles`
+operation. The latter requires one complete zoom level of at most 64 tiles. The former retains
+SceneCapture profiles and per-level LOD distance scales. Both reject manual exposure rather than
+silently ignoring it. Synchronous `CaptureMapTiles` rejects the default Lit backend and directs
+clients to the asynchronous lifecycle.
 
 The editor accepts no output path. It stages only below `Saved/UEShed/MapTileStaging`, reports every
-tile outcome and map package dirty state, and restores transient state before returning. The host
+tile outcome and map package dirty state, and restores transient state when run ownership ends. The host
 must validate staging containment, hash artifacts, and atomically publish only a manifest whose
 state is `complete` and whose tile inventory is exhaustive. Partial and cancelled attempts remain
 diagnostic evidence and are never discoverable as completed runs.

package/contracts/cameras/map-tile/v1/capture-operation.schema.json

@@ -0,0 +1,69 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/map-tile/v1/capture-operation.schema.json",
+	"title": "UE Shed asynchronous map tile operation v1",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["state", "operationId", "completedTiles"],
+			"properties": {
+				"state": {
+					"const": "running"
+				},
+				"operationId": {
+					"$ref": "plan.schema.json#/$defs/id"
+				},
+				"completedTiles": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 64
+				},
+				"phase": {
+					"enum": ["exposure_warmup", "tile_warmup", "capturing"]
+				},
+				"elapsedMs": {
+					"type": "number",
+					"minimum": 0
+				},
+				"totalTiles": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 64
+				},
+				"currentTile": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["zoom", "row", "column"],
+					"properties": {
+						"zoom": {
+							"type": "integer",
+							"minimum": 0
+						},
+						"row": {
+							"type": "integer",
+							"minimum": 0
+						},
+						"column": {
+							"type": "integer",
+							"minimum": 0
+						}
+					}
+				}
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["state", "response"],
+			"properties": {
+				"state": {
+					"const": "finished"
+				},
+				"response": {
+					"$ref": "capture-response.schema.json"
+				}
+			}
+		}
+	]
+}

package/contracts/cameras/map-tile/v1/capture-request.schema.json

@@ -19,8 +19,9 @@
 	"properties": {
 		"capture": { "$ref": "plan.schema.json#/$defs/capturePolicy" },
 		"captureBackend": {
-			"enum": ["scene_capture_tiles", "viewport_high_resolution"]
+			"enum": ["lit_camera_tiles", "scene_capture_tiles", "viewport_high_resolution"]
 		},
+		"overviewBounds": { "$ref": "plan.schema.json#/$defs/bounds" },
 		"contract": {
 			"type": "object",
 			"additionalProperties": false,

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-finished-valid.json

@@ -0,0 +1,41 @@
+{
+	"state": "finished",
+	"response": {
+		"actualMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+		"contract": {
+			"name": "ue-shed-map-tile-capture",
+			"version": {
+				"major": 1,
+				"minor": 0
+			}
+		},
+		"correlationId": "fixture-correlation",
+		"dirtyState": {
+			"before": false,
+			"after": false
+		},
+		"durationMs": 27.5,
+		"operationId": "fixture-operation",
+		"results": [
+			{
+				"bytes": 1234,
+				"captureDurationMs": 20.25,
+				"height": 256,
+				"key": {
+					"zoom": 0,
+					"row": 0,
+					"column": 0
+				},
+				"stagedPath": "C:/Project/Saved/UEShed/MapTileStaging/fixture-run/Z00/R000_C000.png",
+				"status": "captured",
+				"width": 256
+			}
+		],
+		"status": "completed",
+		"tileCounts": {
+			"failed": 0,
+			"requested": 1,
+			"succeeded": 1
+		}
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-progress-valid.json

@@ -0,0 +1,13 @@
+{
+	"state": "running",
+	"operationId": "fixture-operation",
+	"completedTiles": 0,
+	"phase": "tile_warmup",
+	"elapsedMs": 1234,
+	"totalTiles": 4,
+	"currentTile": {
+		"zoom": 0,
+		"row": 0,
+		"column": 0
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-operation-running-valid.json

@@ -0,0 +1,5 @@
+{
+	"state": "running",
+	"operationId": "fixture-operation",
+	"completedTiles": 0
+}

package/contracts/cameras/map-tile/v1/fixtures/capture-request-lit-valid.json

@@ -0,0 +1,59 @@
+{
+	"capture": {
+		"dataLayers": {
+			"mode": "unchanged"
+		},
+		"orientation": {
+			"pitch": -90,
+			"roll": 0,
+			"yaw": 0
+		},
+		"render": {
+			"effects": {
+				"fog": false,
+				"volumetricFog": false
+			},
+			"lodPolicy": "natural",
+			"profile": "full_fidelity",
+			"exposureEV100": -5
+		},
+		"z": 5000
+	},
+	"captureBackend": "lit_camera_tiles",
+	"contract": {
+		"name": "ue-shed-map-tile-capture",
+		"version": {
+			"major": 1,
+			"minor": 0
+		}
+	},
+	"correlationId": "fixture-correlation",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"gutterPixels": 2,
+	"operationId": "fixture-operation",
+	"planId": "fixture-overview",
+	"runId": "fixture-run",
+	"tilePixelSize": 256,
+	"tiles": [
+		{
+			"key": {
+				"zoom": 0,
+				"row": 0,
+				"column": 0
+			},
+			"unitsPerPixel": 4,
+			"worldBounds": {
+				"minX": 1024,
+				"minY": -1024,
+				"maxX": 2048,
+				"maxY": 0
+			}
+		}
+	],
+	"overviewBounds": {
+		"minX": 1024,
+		"minY": -1024,
+		"maxX": 2048,
+		"maxY": 0
+	}
+}

package/contracts/cameras/map-tile/v1/fixtures/readiness-blocked.json

@@ -0,0 +1,11 @@
+{
+	"schemaVersion": 1,
+	"backend": "lit_camera_tiles",
+	"ready": false,
+	"blockers": [
+		{
+			"code": "viewport_locked",
+			"message": "Unlock the viewport."
+		}
+	]
+}

package/contracts/cameras/map-tile/v1/fixtures/readiness-ready.json

@@ -0,0 +1,7 @@
+{
+	"schemaVersion": 1,
+	"backend": "lit_camera_tiles",
+	"ready": true,
+	"actualMapPath": "/Game/Fixture/Map",
+	"blockers": []
+}

package/contracts/cameras/map-tile/v1/fixtures/selection-ready.json

@@ -0,0 +1,21 @@
+{
+	"schemaVersion": 1,
+	"status": "ready",
+	"mapPath": "/Game/Fixture/Map",
+	"bounds": {
+		"minX": -100,
+		"maxX": 100,
+		"minY": 50,
+		"maxY": 250,
+		"minZ": 0,
+		"maxZ": 400
+	},
+	"actors": [
+		{
+			"path": "/Game/Fixture/Map.A",
+			"label": "A",
+			"actorGuid": "00000001000000020000000300000004"
+		}
+	],
+	"skippedActorPaths": []
+}

package/contracts/cameras/map-tile/v1/fixtures/selection-unavailable.json

@@ -0,0 +1,6 @@
+{
+	"schemaVersion": 1,
+	"status": "unavailable",
+	"code": "selection_limit",
+	"message": "Select between 1 and 1024 actors."
+}

package/contracts/cameras/map-tile/v1/inspection.md

@@ -0,0 +1,16 @@
+# Capture inspection v1
+
+`InspectMapCaptureSelection` requires `cameras.capture-selection.v1`. It reads selection in the
+current editor world, rejects PIE and selections outside 1–1024 actors, and combines finite component
+bounds. `skippedActorPaths` identifies actors without usable bounds or in another world. Ready bounds
+must satisfy min <= max on every axis; planar/point selections are valid. Host plan fitting supplies
+positive XY extent. The operation neither modifies selection nor loads additional regions.
+
+`InspectMapCaptureReadiness(ExpectedMapPath)` requires `cameras.capture-readiness.v1` and applies to
+Lit capture. `ready` is true exactly when `blockers` is empty. It checks map identity, rendering,
+streaming, viewport locking/overrides, screenshot use, PIE and capture ownership. It does not reserve
+resources, load regions, or guarantee visual completeness. Capture execution repeats shared checks.
+
+The running operation's optional phase/elapsed/count/current-tile fields are telemetry for the current
+batch. `currentTile` is absent during whole-map exposure warmup. Existing responses without these
+fields remain valid. Terminal responses and publication rules are unchanged.

package/contracts/cameras/map-tile/v1/plan.schema.json

@@ -130,6 +130,7 @@
 					"additionalProperties": false,
 					"required": ["effects", "lodPolicy", "profile"],
 					"properties": {
+						"exposureEV100": { "type": "number", "minimum": -20, "maximum": 30 },
 						"effects": {
 							"type": "object",
 							"additionalProperties": false,

package/contracts/cameras/map-tile/v1/readiness.schema.json

@@ -0,0 +1,39 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schemaVersion", "backend", "ready", "blockers"],
+	"properties": {
+		"schemaVersion": {
+			"const": 1
+		},
+		"backend": {
+			"const": "lit_camera_tiles"
+		},
+		"ready": {
+			"type": "boolean"
+		},
+		"actualMapPath": {
+			"type": "string",
+			"minLength": 1
+		},
+		"blockers": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["code", "message"],
+				"properties": {
+					"code": {
+						"type": "string",
+						"minLength": 1
+					},
+					"message": {
+						"type": "string",
+						"minLength": 1
+					}
+				}
+			}
+		}
+	}
+}

package/contracts/cameras/map-tile/v1/selection.schema.json

@@ -0,0 +1,105 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schemaVersion",
+				"status",
+				"mapPath",
+				"bounds",
+				"actors",
+				"skippedActorPaths"
+			],
+			"properties": {
+				"schemaVersion": {
+					"const": 1
+				},
+				"status": {
+					"const": "ready"
+				},
+				"mapPath": {
+					"type": "string",
+					"minLength": 1
+				},
+				"bounds": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["minX", "maxX", "minY", "maxY", "minZ", "maxZ"],
+					"properties": {
+						"minX": {
+							"type": "number"
+						},
+						"maxX": {
+							"type": "number"
+						},
+						"minY": {
+							"type": "number"
+						},
+						"maxY": {
+							"type": "number"
+						},
+						"minZ": {
+							"type": "number"
+						},
+						"maxZ": {
+							"type": "number"
+						}
+					}
+				},
+				"actors": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["path", "label"],
+						"properties": {
+							"path": {
+								"type": "string",
+								"minLength": 1
+							},
+							"label": {
+								"type": "string"
+							},
+							"actorGuid": {
+								"type": "string",
+								"pattern": "^[0-9A-Fa-f]{32}$"
+							}
+						}
+					},
+					"minItems": 1,
+					"maxItems": 1024
+				},
+				"skippedActorPaths": {
+					"type": "array",
+					"items": {
+						"type": "string"
+					},
+					"maxItems": 1024
+				}
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["schemaVersion", "status", "code", "message"],
+			"properties": {
+				"schemaVersion": {
+					"const": 1
+				},
+				"status": {
+					"const": "unavailable"
+				},
+				"code": {
+					"type": "string",
+					"minLength": 1
+				},
+				"message": {
+					"type": "string",
+					"minLength": 1
+				}
+			}
+		}
+	]
+}

package/contracts/cameras/review/v1/README.md

@@ -17,7 +17,15 @@ visibility measurement: the plugin reports what it observed and does not assign
 original engine-produced classification. Minor version 4 adds one optional Clear companion to the
 same capture operation. Its request carries only an effective producer instruction (`isolate_target`
 or bounded `hide_explicit` actor paths); consumer policy, thresholds, and presentation remain
-outside the wire contract.
+outside the wire contract. Minor version 5 adds the durable `actor_guid` subject locator. The GUID
+is Unreal's authored actor GUID (`FGuid::UniqueObjectGuid`); a last-known actor path is diagnostic
+evidence only and is never used as an identity fallback.
+
+Producers accept every complete, schema-valid 1.x request through the highest minor they advertise.
+They echo the accepted request minor in both success and failure responses. Missing, fractional,
+negative, or future minors; unknown major versions; minor-feature contradictions; and excess fields
+are rejected deterministically. Once a request supplies an operation ID and view ID, a structured
+failure retains those identities even when contract negotiation fails.
 
 The editor resolves an actor-relative pose atomically from the actor's current transform. Its
 response records the resolved target, exact effective world pose, projection, bounded visibility

package/contracts/cameras/review/v1/capture-request.schema.json

@@ -18,23 +18,53 @@
 					"required": ["major", "minor"],
 					"properties": {
 						"major": { "const": 1 },
-						"minor": { "type": "integer", "minimum": 0, "maximum": 4 }
+						"minor": { "type": "integer", "minimum": 0, "maximum": 5 }
 					}
 				}
 			}
 		},
-		"operationId": { "type": "string", "format": "uuid" },
+		"operationId": {
+			"type": "string",
+			"format": "uuid",
+			"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+			"not": { "const": "00000000-0000-0000-0000-000000000000" }
+		},
 		"viewId": { "$ref": "#/$defs/safeId" },
 		"expectedMapPath": { "type": "string", "minLength": 1 },
 		"subject": {
 			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["kind", "actorGuid"],
+					"properties": {
+						"kind": { "const": "actor_guid" },
+						"actorGuid": {
+							"type": "string",
+							"pattern": "^[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{8}){3}$",
+							"not": { "const": "00000000-00000000-00000000-00000000" }
+						},
+						"lastKnownActorPath": {
+							"type": "string",
+							"minLength": 7,
+							"maxLength": 4096,
+							"pattern": "^/Game/"
+						},
+						"diagnosticLabel": { "type": "string", "minLength": 1 }
+					}
+				},
 				{
 					"type": "object",
 					"additionalProperties": false,
 					"required": ["kind", "actorPath"],
 					"properties": {
 						"kind": { "const": "actor_path" },
-						"actorPath": { "type": "string", "minLength": 1 },
+						"actorPath": {
+							"type": "string",
+							"minLength": 7,
+							"maxLength": 4096,
+							"pattern": "^/Game/"
+						},
 						"diagnosticLabel": { "type": "string", "minLength": 1 }
 					}
 				},
@@ -80,7 +110,7 @@
 				"properties": {
 					"contract": {
 						"properties": {
-							"version": { "properties": { "minor": { "enum": [2, 3, 4] } } }
+							"version": { "properties": { "minor": { "enum": [2, 3, 4, 5] } } }
 						}
 					}
 				}
@@ -93,13 +123,32 @@
 				"properties": {
 					"contract": {
 						"properties": {
-							"version": { "properties": { "minor": { "const": 4 } } }
+							"version": { "properties": { "minor": { "enum": [4, 5] } } }
 						}
 					}
 				}
 			},
 			"then": { "required": ["clearCompanion"] },
 			"else": { "not": { "required": ["clearCompanion"] } }
+		},
+		{
+			"if": {
+				"properties": {
+					"subject": {
+						"required": ["kind"],
+						"properties": { "kind": { "const": "actor_guid" } }
+					}
+				}
+			},
+			"then": {
+				"properties": {
+					"contract": {
+						"properties": {
+							"version": { "properties": { "minor": { "const": 5 } } }
+						}
+					}
+				}
+			}
 		}
 	],
 	"$defs": {