@ue-shed/protocol 0.5.1 → 0.7.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.
@@ -42,3 +56,10 @@ Control payload rather than giving it hidden editor authority.
 
 Change this contract in authority order: JSON Schema and fixtures, conformant Effect codecs,
 UEShedCameras C++ producer with trusted UE 5.7 evidence, then consumers.
+
+Minor 1 adds source `renderEvidence` to capture responses and immutable manifests. The source
+frame resolution can differ from a published tile after gutter cropping, supersampling or slicing.
+`release-result.schema.json` describes the EndMapTileCapture result for this lifecycle; callers
+must require `restoration: restored` before publication. A false `released` means the specified run
+did not own the map adapter; it never releases another owner. Renderer ownership is shared with
+the camera render 1.0 and Review adapters.

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/capture-response.schema.json

@@ -15,26 +15,49 @@
 		"tileCounts"
 	],
 	"properties": {
-		"actualMapPath": { "type": "string", "pattern": "^/[A-Za-z0-9_./-]+$" },
+		"actualMapPath": {
+			"type": "string",
+			"pattern": "^/[A-Za-z0-9_./-]+$"
+		},
 		"contract": {
 			"type": "object",
 			"additionalProperties": false,
 			"required": ["name", "version"],
 			"properties": {
-				"name": { "const": "ue-shed-map-tile-capture" },
-				"version": { "$ref": "plan.schema.json#/$defs/version" }
+				"name": {
+					"const": "ue-shed-map-tile-capture"
+				},
+				"version": {
+					"$ref": "plan.schema.json#/$defs/version"
+				}
 			}
 		},
-		"correlationId": { "$ref": "plan.schema.json#/$defs/id" },
+		"correlationId": {
+			"$ref": "plan.schema.json#/$defs/id"
+		},
 		"dirtyState": {
 			"type": "object",
 			"additionalProperties": false,
 			"required": ["before", "after"],
-			"properties": { "before": { "type": "boolean" }, "after": { "type": "boolean" } }
+			"properties": {
+				"before": {
+					"type": "boolean"
+				},
+				"after": {
+					"type": "boolean"
+				}
+			}
+		},
+		"durationMs": {
+			"type": "number",
+			"minimum": 0
+		},
+		"failure": {
+			"$ref": "#/$defs/failure"
+		},
+		"operationId": {
+			"$ref": "plan.schema.json#/$defs/id"
 		},
-		"durationMs": { "type": "number", "minimum": 0 },
-		"failure": { "$ref": "#/$defs/failure" },
-		"operationId": { "$ref": "plan.schema.json#/$defs/id" },
 		"results": {
 			"type": "array",
 			"maxItems": 64,
@@ -53,13 +76,35 @@
 							"width"
 						],
 						"properties": {
-							"bytes": { "type": "integer", "minimum": 1 },
-							"captureDurationMs": { "type": "number", "minimum": 0 },
-							"height": { "type": "integer", "minimum": 1 },
-							"key": { "$ref": "capture-request.schema.json#/$defs/tileKey" },
-							"stagedPath": { "type": "string", "minLength": 1 },
-							"status": { "const": "captured" },
-							"width": { "type": "integer", "minimum": 1 }
+							"bytes": {
+								"type": "integer",
+								"minimum": 1
+							},
+							"captureDurationMs": {
+								"type": "number",
+								"minimum": 0
+							},
+							"height": {
+								"type": "integer",
+								"minimum": 1
+							},
+							"key": {
+								"$ref": "capture-request.schema.json#/$defs/tileKey"
+							},
+							"stagedPath": {
+								"type": "string",
+								"minLength": 1
+							},
+							"status": {
+								"const": "captured"
+							},
+							"width": {
+								"type": "integer",
+								"minimum": 1
+							},
+							"renderEvidence": {
+								"$ref": "../../render/v1/frame-evidence.schema.json"
+							}
 						}
 					},
 					{
@@ -67,23 +112,40 @@
 						"additionalProperties": false,
 						"required": ["failure", "key", "status"],
 						"properties": {
-							"failure": { "$ref": "#/$defs/failure" },
-							"key": { "$ref": "capture-request.schema.json#/$defs/tileKey" },
-							"status": { "const": "failed" }
+							"failure": {
+								"$ref": "#/$defs/failure"
+							},
+							"key": {
+								"$ref": "capture-request.schema.json#/$defs/tileKey"
+							},
+							"status": {
+								"const": "failed"
+							}
 						}
 					}
 				]
 			}
 		},
-		"status": { "enum": ["completed", "partial", "cancelled", "failed"] },
+		"status": {
+			"enum": ["completed", "partial", "cancelled", "failed"]
+		},
 		"tileCounts": {
 			"type": "object",
 			"additionalProperties": false,
 			"required": ["failed", "requested", "succeeded"],
 			"properties": {
-				"failed": { "type": "integer", "minimum": 0 },
-				"requested": { "type": "integer", "minimum": 0 },
-				"succeeded": { "type": "integer", "minimum": 0 }
+				"failed": {
+					"type": "integer",
+					"minimum": 0
+				},
+				"requested": {
+					"type": "integer",
+					"minimum": 0
+				},
+				"succeeded": {
+					"type": "integer",
+					"minimum": 0
+				}
 			}
 		}
 	},
@@ -106,9 +168,19 @@
 						"write_failed"
 					]
 				},
-				"message": { "type": "string", "minLength": 1, "maxLength": 1024 },
-				"recovery": { "type": "string", "minLength": 1, "maxLength": 1024 },
-				"retrySafe": { "type": "boolean" }
+				"message": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 1024
+				},
+				"recovery": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 1024
+				},
+				"retrySafe": {
+					"type": "boolean"
+				}
 			}
 		}
 	}

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.