@ue-shed/protocol 0.1.0-rc.1

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

@@ -0,0 +1,39 @@
+# Map Review capture contract v1
+
+The checked-in JSON Schemas in this directory are the language-neutral authority for the stable
+editor wire surface shared by TypeScript and UEShedCameras: capture request/response and selection /
+subject-inspection response. TypeScript Effect codecs in `@ue-shed/cameras` and the Unreal C++
+companion must remain conformant with them.
+
+Portable Review Set / Capture Run documents and Workbench IPC remain TypeScript-owned Effect schemas
+in `@ue-shed/cameras`. They are deliberately outside this JSON authority while Map Review authoring
+recovery, live preview, and World Scout streaming plans remain active.
+
+The control-plane request asks a separately enabled editor capability to resolve one actor subject,
+realize one approved perspective pose transiently, and write one Pure PNG into the project's bounded
+review staging directory. The response reports the staged path, effective dimensions, resolved map
+and subject, duration, and map-package dirty state before and after capture.
+
+The staged file is not durable evidence. A trusted host validates that the path is beneath
+`Saved/UEShed/ReviewStaging`, hashes and copies the PNG into an immutable Capture Run, then deletes the
+staged file. The editor capability never accepts an arbitrary output path.
+
+Requests and responses declare `ue-shed-review-capture` contract major version 1. Expected failures
+are structured, include recovery guidance and retry safety, and never masquerade as captured images.
+
+`selection-response.schema.json` defines the adjacent editor-only spatial-authoring observation. It
+returns one selected actor's normalized bounds and optional active perspective viewport, or a typed
+no-selection, multiple-selection, or editor-unavailable failure. The same schema file also documents
+subject-inspection failures (`map_mismatch`, `subject_not_found`); TypeScript keeps ambient selection
+and subject-inspection as separate Effect unions that both conform to this JSON envelope. Candidate
+generation and approval are deliberately outside this wire contract.
+
+Change a wire shape in this order:
+
+1. Edit the authoritative JSON Schema and add or update language-neutral conformance fixtures.
+2. Update the Effect runtime schema until `pnpm --filter @ue-shed/cameras contract:check` passes.
+3. Update the UEShedCameras producer and run `pnpm check:unreal` (review lane) on a trusted UE 5.7
+   runner with Remote Control connected.
+4. Switch consumers only after both producers pass.
+
+Do not generate these files from TypeScript. That would reverse the authority established by ADR 0002.

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

@@ -0,0 +1,92 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/review/v1/capture-request.schema.json",
+	"title": "UE Shed Map Review capture request v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"contract",
+		"operationId",
+		"viewId",
+		"expectedMapPath",
+		"subject",
+		"approvedPose",
+		"resolution"
+	],
+	"properties": {
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "ue-shed-review-capture" },
+				"version": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["major", "minor"],
+					"properties": {
+						"major": { "const": 1 },
+						"minor": { "type": "integer", "minimum": 0 }
+					}
+				}
+			}
+		},
+		"operationId": { "type": "string", "format": "uuid" },
+		"viewId": { "$ref": "#/$defs/safeId" },
+		"expectedMapPath": { "type": "string", "minLength": 1 },
+		"subject": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["kind", "actorPath"],
+			"properties": {
+				"kind": { "const": "actor_path" },
+				"actorPath": { "type": "string", "minLength": 1 },
+				"diagnosticLabel": { "type": "string", "minLength": 1 }
+			}
+		},
+		"approvedPose": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["aspectRatio", "fieldOfViewDegrees", "location", "projection", "rotation"],
+			"properties": {
+				"aspectRatio": { "const": "16:9" },
+				"fieldOfViewDegrees": { "type": "number", "minimum": 5, "maximum": 170 },
+				"projection": { "const": "perspective" },
+				"location": { "$ref": "#/$defs/vector" },
+				"rotation": { "$ref": "#/$defs/rotation" }
+			}
+		},
+		"resolution": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["width", "height"],
+			"properties": {
+				"width": { "type": "integer", "minimum": 160, "maximum": 3840 },
+				"height": { "type": "integer", "minimum": 90, "maximum": 2160 }
+			}
+		}
+	},
+	"$defs": {
+		"safeId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+		"vector": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["x", "y", "z"],
+			"properties": {
+				"x": { "type": "number" },
+				"y": { "type": "number" },
+				"z": { "type": "number" }
+			}
+		},
+		"rotation": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["pitch", "yaw", "roll"],
+			"properties": {
+				"pitch": { "type": "number" },
+				"yaw": { "type": "number" },
+				"roll": { "type": "number" }
+			}
+		}
+	}
+}

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

@@ -0,0 +1,158 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/review/v1/capture-response.schema.json",
+	"title": "UE Shed Map Review capture response v1",
+	"oneOf": [
+		{
+			"type": "object",
+			"required": [
+				"contract",
+				"status",
+				"operationId",
+				"viewId",
+				"actorPath",
+				"mapPath",
+				"stagingPath",
+				"width",
+				"height",
+				"captureDurationMs",
+				"mapPackageDirtyBefore",
+				"mapPackageDirtyAfter"
+			],
+			"properties": {
+				"contract": { "$ref": "#/$defs/contract" },
+				"status": { "const": "captured" },
+				"operationId": { "type": "string", "minLength": 1 },
+				"viewId": { "$ref": "#/$defs/safeId" },
+				"actorPath": { "type": "string", "minLength": 1 },
+				"mapPath": { "type": "string", "minLength": 1 },
+				"stagingPath": { "type": "string", "minLength": 1 },
+				"width": { "type": "integer", "minimum": 1 },
+				"height": { "type": "integer", "minimum": 1 },
+				"captureDurationMs": { "type": "number", "minimum": 0 },
+				"mapPackageDirtyBefore": { "type": "boolean" },
+				"mapPackageDirtyAfter": { "type": "boolean" },
+				"subjectProjection": { "$ref": "#/$defs/subjectProjection" }
+			},
+			"allOf": [
+				{
+					"if": {
+						"required": ["contract"],
+						"properties": {
+							"contract": {
+								"required": ["version"],
+								"properties": {
+									"version": {
+										"required": ["minor"],
+										"properties": {
+											"minor": { "minimum": 1 }
+										}
+									}
+								}
+							}
+						}
+					},
+					"then": { "required": ["subjectProjection"] }
+				}
+			],
+			"additionalProperties": false
+		},
+		{
+			"type": "object",
+			"required": [
+				"contract",
+				"status",
+				"operationId",
+				"viewId",
+				"code",
+				"message",
+				"recovery",
+				"retrySafe"
+			],
+			"properties": {
+				"contract": { "$ref": "#/$defs/contract" },
+				"status": { "const": "failed" },
+				"operationId": { "type": "string" },
+				"viewId": { "type": "string" },
+				"code": { "type": "string", "minLength": 1 },
+				"message": { "type": "string", "minLength": 1 },
+				"recovery": { "type": "string", "minLength": 1 },
+				"retrySafe": { "type": "boolean" }
+			},
+			"additionalProperties": false
+		}
+	],
+	"$defs": {
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "ue-shed-review-capture" },
+				"version": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["major", "minor"],
+					"properties": {
+						"major": { "const": 1 },
+						"minor": { "type": "integer", "minimum": 0 }
+					}
+				}
+			}
+		},
+		"safeId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+		"projectedBounds": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["minX", "minY", "maxX", "maxY"],
+			"properties": {
+				"minX": { "type": "number" },
+				"minY": { "type": "number" },
+				"maxX": { "type": "number" },
+				"maxY": { "type": "number" }
+			}
+		},
+		"projectionMargins": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["left", "right", "top", "bottom"],
+			"properties": {
+				"left": { "type": "number" },
+				"right": { "type": "number" },
+				"top": { "type": "number" },
+				"bottom": { "type": "number" }
+			}
+		},
+		"subjectProjection": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["status", "viewportStatus", "normalizedBounds", "margins"],
+					"properties": {
+						"status": { "const": "projected" },
+						"viewportStatus": {
+							"enum": [
+								"fully_within_viewport",
+								"partially_outside_viewport",
+								"fully_outside_viewport"
+							]
+						},
+						"normalizedBounds": { "$ref": "#/$defs/projectedBounds" },
+						"margins": { "$ref": "#/$defs/projectionMargins" }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["status", "code", "message"],
+					"properties": {
+						"status": { "const": "unprojectable" },
+						"code": { "enum": ["behind_camera", "near_plane_crossing"] },
+						"message": { "type": "string", "minLength": 1 }
+					}
+				}
+			]
+		}
+	}
+}

package/contracts/cameras/review/v1/fixtures/capture-failure.json

@@ -0,0 +1,13 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"status": "failed",
+	"operationId": "33333333-3333-4333-8333-333333333333",
+	"viewId": "structure-context",
+	"code": "invalid_request",
+	"message": "Review capture request is not valid JSON.",
+	"recovery": "Validate the request against contract version 1.",
+	"retrySafe": false
+}

package/contracts/cameras/review/v1/fixtures/capture-legacy.json

@@ -0,0 +1,17 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"status": "captured",
+	"operationId": "capture-legacy",
+	"viewId": "structure-context",
+	"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-legacy/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 9.5,
+	"mapPackageDirtyBefore": false,
+	"mapPackageDirtyAfter": false
+}

package/contracts/cameras/review/v1/fixtures/capture-projected.json

@@ -0,0 +1,33 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 1 }
+	},
+	"status": "captured",
+	"operationId": "capture-1",
+	"viewId": "structure-context",
+	"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-1/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 12.5,
+	"mapPackageDirtyBefore": false,
+	"mapPackageDirtyAfter": false,
+	"subjectProjection": {
+		"status": "projected",
+		"viewportStatus": "fully_within_viewport",
+		"normalizedBounds": {
+			"minX": 0.25,
+			"minY": 0.2,
+			"maxX": 0.75,
+			"maxY": 0.8
+		},
+		"margins": {
+			"left": 0.25,
+			"right": 0.25,
+			"top": 0.2,
+			"bottom": 0.2
+		}
+	}
+}

package/contracts/cameras/review/v1/fixtures/capture-request-valid.json

@@ -0,0 +1,21 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 1 }
+	},
+	"operationId": "11111111-1111-4111-8111-111111111111",
+	"viewId": "structure-context",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"subject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject"
+	},
+	"approvedPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 70,
+		"projection": "perspective",
+		"location": { "x": 100, "y": 200, "z": 300 },
+		"rotation": { "pitch": -20, "yaw": 45, "roll": 0 }
+	},
+	"resolution": { "width": 1280, "height": 720 }
+}

package/contracts/cameras/review/v1/fixtures/capture-unprojectable.json

@@ -0,0 +1,22 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 1 }
+	},
+	"status": "captured",
+	"operationId": "capture-2",
+	"viewId": "structure-context",
+	"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-2/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 10.5,
+	"mapPackageDirtyBefore": false,
+	"mapPackageDirtyAfter": false,
+	"subjectProjection": {
+		"status": "unprojectable",
+		"code": "near_plane_crossing",
+		"message": "A subject-bounds corner crosses the transient capture near plane."
+	}
+}

package/contracts/cameras/review/v1/fixtures/invalid-capture-request-bad-fov.json

@@ -0,0 +1,21 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 1 }
+	},
+	"operationId": "22222222-2222-4222-8222-222222222222",
+	"viewId": "structure-context",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"subject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject"
+	},
+	"approvedPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 1,
+		"projection": "perspective",
+		"location": { "x": 0, "y": 0, "z": 0 },
+		"rotation": { "pitch": 0, "yaw": 0, "roll": 0 }
+	},
+	"resolution": { "width": 1280, "height": 720 }
+}

package/contracts/cameras/review/v1/fixtures/invalid-capture-response-projected-without-margins.json

@@ -0,0 +1,27 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 1 }
+	},
+	"status": "captured",
+	"operationId": "capture-bad-projection",
+	"viewId": "structure-context",
+	"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-bad/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 12.5,
+	"mapPackageDirtyBefore": false,
+	"mapPackageDirtyAfter": false,
+	"subjectProjection": {
+		"status": "projected",
+		"viewportStatus": "fully_within_viewport",
+		"normalizedBounds": {
+			"minX": 0.2,
+			"minY": 0.2,
+			"maxX": 0.8,
+			"maxY": 0.8
+		}
+	}
+}

package/contracts/cameras/review/v1/fixtures/invalid-selection-unknown-code.json

@@ -0,0 +1,11 @@
+{
+	"contract": {
+		"name": "ue-shed-review-selection",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"status": "failed",
+	"code": "not_a_real_failure",
+	"message": "Invented failure code.",
+	"recovery": "Do not accept unknown codes.",
+	"retrySafe": false
+}

package/contracts/cameras/review/v1/fixtures/selection-selected.json

@@ -0,0 +1,15 @@
+{
+	"contract": {
+		"name": "ue-shed-review-selection",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"status": "selected",
+	"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+	"displayName": "ReviewSubject",
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"bounds": {
+		"center": { "x": 0, "y": 0, "z": 100 },
+		"extent": { "x": 50, "y": 50, "z": 100 },
+		"rotation": { "pitch": 0, "yaw": 0, "roll": 0 }
+	}
+}

package/contracts/cameras/review/v1/fixtures/selection-subject-not-found.json

@@ -0,0 +1,11 @@
+{
+	"contract": {
+		"name": "ue-shed-review-selection",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"status": "failed",
+	"code": "subject_not_found",
+	"message": "The persisted review subject was not found.",
+	"recovery": "Restore the subject or discard this authoring session.",
+	"retrySafe": true
+}

package/contracts/cameras/review/v1/selection-response.schema.json

@@ -0,0 +1,103 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/review/v1/selection-response.schema.json",
+	"title": "UE Shed Review Selection Response v1",
+	"oneOf": [
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["contract", "status", "actorPath", "displayName", "mapPath", "bounds"],
+			"properties": {
+				"contract": { "$ref": "#/$defs/contract" },
+				"status": { "const": "selected" },
+				"actorPath": { "type": "string", "minLength": 1 },
+				"displayName": { "type": "string", "minLength": 1 },
+				"mapPath": { "type": "string", "minLength": 1 },
+				"bounds": { "$ref": "#/$defs/bounds" },
+				"editorView": { "$ref": "#/$defs/pose" }
+			}
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["contract", "status", "code", "message", "recovery", "retrySafe"],
+			"properties": {
+				"contract": { "$ref": "#/$defs/contract" },
+				"status": { "const": "failed" },
+				"code": {
+					"enum": [
+						"no_selection",
+						"multiple_selection",
+						"editor_unavailable",
+						"map_mismatch",
+						"subject_not_found"
+					]
+				},
+				"message": { "type": "string", "minLength": 1 },
+				"recovery": { "type": "string", "minLength": 1 },
+				"retrySafe": { "type": "boolean" }
+			}
+		}
+	],
+	"$defs": {
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "ue-shed-review-selection" },
+				"version": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["major", "minor"],
+					"properties": {
+						"major": { "const": 1 },
+						"minor": { "type": "integer", "minimum": 0 }
+					}
+				}
+			}
+		},
+		"vector": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["x", "y", "z"],
+			"properties": {
+				"x": { "type": "number" },
+				"y": { "type": "number" },
+				"z": { "type": "number" }
+			}
+		},
+		"rotation": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["pitch", "roll", "yaw"],
+			"properties": {
+				"pitch": { "type": "number" },
+				"roll": { "type": "number" },
+				"yaw": { "type": "number" }
+			}
+		},
+		"bounds": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["center", "extent", "rotation"],
+			"properties": {
+				"center": { "$ref": "#/$defs/vector" },
+				"extent": { "$ref": "#/$defs/vector" },
+				"rotation": { "$ref": "#/$defs/rotation" }
+			}
+		},
+		"pose": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["aspectRatio", "fieldOfViewDegrees", "location", "projection", "rotation"],
+			"properties": {
+				"aspectRatio": { "const": "16:9" },
+				"fieldOfViewDegrees": { "type": "number", "minimum": 5, "maximum": 170 },
+				"location": { "$ref": "#/$defs/vector" },
+				"projection": { "const": "perspective" },
+				"rotation": { "$ref": "#/$defs/rotation" }
+			}
+		}
+	}
+}

package/contracts/cameras/v1/README.md

@@ -0,0 +1,33 @@
+# Camera live-frame contract v1
+
+The live path is a byte stream of fixed-size 128-byte little-endian headers followed immediately by
+`payloadLength` bytes. Receivers must resynchronize on the ASCII magic `USCF`, reject unsupported
+versions and dimensions, and cap payloads before allocating. A reconnect starts a new session ID;
+frames from an old session are disposable.
+
+| Offset | Type    | Field                                                |
+| -----: | ------- | ---------------------------------------------------- |
+|      0 | char[4] | `USCF` magic                                         |
+|      4 | u16     | version (`1`)                                        |
+|      6 | u16     | header length (`128`)                                |
+|      8 | u32     | flags: bit 0 sRGB, bit 1 BGRA8                       |
+|     12 | u32     | width                                                |
+|     16 | u32     | height                                               |
+|     20 | u32     | row pitch in bytes (payload is tightly packed in v1) |
+|     24 | u32     | payload length                                       |
+|     28 | u32     | stable fixture camera index                          |
+|     32 | u64     | per-camera sequence                                  |
+|     40 | f64     | Unreal world seconds at capture request              |
+|     48 | f64     | producer monotonic milliseconds at capture request   |
+|     56 | f64     | GPU readback latency in milliseconds                 |
+|     64 | u8[16]  | producer ID                                          |
+|     80 | u8[16]  | session ID                                           |
+|     96 | u8[16]  | camera ID                                            |
+|    112 | u32     | cumulative readback/staging drops                    |
+|    116 | u32     | cumulative latest-frame transport replacements       |
+|    120 | u32     | reserved, zero                                       |
+|    124 | u32     | reserved, zero                                       |
+
+The payload is top-to-bottom, tightly packed BGRA8. Live buffers are bounded and latest-frame-wins;
+sequence gaps are expected and observable. The control plane owns camera listing, schedule tuning,
+pause/focus, and health. This binary stream never carries durable evidence.

package/contracts/editor-session/v1/README.md

@@ -0,0 +1,11 @@
+# Unreal editor play-session contract v1
+
+These JSON Schemas are the language-neutral authority for observing and controlling a local Unreal
+Editor play session. Commands are idempotent and return the state observed immediately after the
+request. Lifecycle completion remains observable through subsequent state queries.
+
+`play` means Play In Editor and `simulate` means Simulate In Editor. Version 1 targets one local,
+single-process session in the active level viewport. Standalone and multiplayer launch profiles are
+outside this contract.
+
+The JSON fixtures are shared examples for TypeScript and Unreal-side conformance tests.