@ue-shed/protocol 0.1.0-rc.4 → 0.1.0

package/README.md

@@ -4,7 +4,7 @@ Runtime schemas, branded identifiers, compatibility values, and versioned wire c
 UE Shed clients and Unreal companion plugins.
 
 ```sh
-npm install @ue-shed/protocol@0.1.0-rc.4 effect@4.0.0-beta.98
+npm install --save-exact @ue-shed/protocol effect@4.0.0-beta.98
 ```
 
 The package supports Node.js 22.14 or newer and exposes one stable JavaScript entry point:

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

@@ -0,0 +1,12 @@
+# Provisioned camera contract v1
+
+`EnsureProvisionedCameras` accepts this bounded JSON request through Remote Control. A provisioned
+camera is a transient runtime realization, identified by a generated `ProvisionedCameraId`; it is
+never a durable Map Review camera record.
+
+Each request carries an explicit correlation to either a framing candidate or a durable Review View.
+The compatibility decoder accepts the former candidate-only request shape for already-installed
+clients, but new clients emit only `schemaVersion: 2` and the `correlation` union.
+
+The editor returns the same correlation for every provisioned camera. Array index remains a live
+frame transport position, never durable identity.

package/contracts/cameras/provisioning/v1/fixtures/provision-request-valid.json

@@ -0,0 +1,14 @@
+{
+	"schemaVersion": 2,
+	"previewFps": 5,
+	"cameras": [
+		{
+			"correlation": { "type": "framing_candidate", "candidateId": "context_three_quarter" },
+			"fieldOfViewDegrees": 60,
+			"location": { "x": 1200, "y": -1400, "z": 700 },
+			"rotation": { "pitch": -12, "yaw": 135, "roll": 0 },
+			"width": 320,
+			"height": 180
+		}
+	]
+}

package/contracts/cameras/provisioning/v1/provision-request.schema.json

@@ -0,0 +1,90 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/provisioning/v1/provision-request.schema.json",
+	"title": "UE Shed provisioned camera request v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schemaVersion", "previewFps", "cameras"],
+	"properties": {
+		"schemaVersion": { "const": 2 },
+		"previewFps": { "type": "integer", "minimum": 1, "maximum": 10 },
+		"cameras": {
+			"type": "array",
+			"minItems": 1,
+			"maxItems": 32,
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": [
+					"correlation",
+					"fieldOfViewDegrees",
+					"location",
+					"rotation",
+					"width",
+					"height"
+				],
+				"properties": {
+					"correlation": {
+						"oneOf": [
+							{
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["type", "candidateId"],
+								"properties": {
+									"type": { "const": "framing_candidate" },
+									"candidateId": {
+										"type": "string",
+										"minLength": 1,
+										"maxLength": 128,
+										"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+									}
+								}
+							},
+							{
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["type", "reviewViewId"],
+								"properties": {
+									"type": { "const": "review_view" },
+									"reviewViewId": {
+										"type": "string",
+										"minLength": 1,
+										"maxLength": 128,
+										"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+									}
+								}
+							}
+						]
+					},
+					"fieldOfViewDegrees": { "type": "number", "minimum": 5, "maximum": 170 },
+					"location": { "$ref": "#/$defs/vector" },
+					"rotation": { "$ref": "#/$defs/rotation" },
+					"width": { "type": "integer", "minimum": 64, "maximum": 2560 },
+					"height": { "type": "integer", "minimum": 64, "maximum": 1440 }
+				}
+			}
+		}
+	},
+	"$defs": {
+		"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/README.md

@@ -1,22 +1,51 @@
 # 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.
+editor wire surface shared by TypeScript and UEShedCameras: capture request/response, optional
+assessment capabilities, 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.
+Minor versions 0–1 accept the original actor plus approved-world-pose request. Minor version 2 adds
+actor or oriented-bounds subjects, world-fixed or actor-relative viewpoints, and a requested
+visibility-assessment method. Minor version 3 keeps those inputs but makes the editor response a raw
+visibility measurement: the plugin reports what it observed and does not assign a product-facing
+`clear`, `partial`, or `blocked` classification. Version 2 responses remain readable with their
+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.
 
-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.
+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
+measurement, staged Pure image, optional staged Clear companion, duration, and map-package dirty
+state. The companion reports its explicit component-list intervention and restoration outcome; a
+Clear failure retains Pure evidence as a typed partial result. Current Capture Runs preserve that raw
+measurement. `@ue-shed/cameras` provides an optional pure classification helper only when a consumer
+supplies its own thresholds; UE Shed does not prescribe defaults. Capture Run v1.2 classifications
+remain readable after migration as explicitly legacy interpretation rather than current evidence.
+
+For version 3 actor requests, `automatic` resolves to a bounded render-truthful depth comparison.
+The editor makes one full-scene depth capture and one subject-only depth capture at no more than
+320×180, then reports the fraction of subject-depth pixels that remain visible in the full scene.
+The method records its version and limitations; translucent or otherwise non-depth-writing subjects
+fail assessment instead of producing a fabricated percentage. Explicit `ray_samples` remains
+available as a cheaper diagnostic because collision and rendered visibility can disagree.
+Unprojectable or fully offscreen v1.3 requests also return `not_assessed`, with the projection
+diagnosis preserved separately. Oriented-area requests return `not_assessed`; area contents are not
+treated as blockers. The requested subject-mask method remains unsupported.
+
+`assessment-capabilities.schema.json` describes an optional producer fact report. It records which
+requested assessment methods are supported by this editor, their effective method/version, and the
+maximum depth-comparison render size. It does not select a method, classify a measurement, or set
+consumer visibility thresholds; callers may ignore it and use capture responses alone.
+
+Staged files are not durable evidence. A trusted host validates that every path is beneath
+`Saved/UEShed/ReviewStaging`, hashes and copies each PNG into an immutable Capture Run, then deletes
+the staged files. 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.

package/contracts/cameras/review/v1/assessment-capabilities.schema.json

@@ -0,0 +1,86 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://ue-shed.dev/contracts/cameras/review/v1/assessment-capabilities.schema.json",
+	"title": "UE Shed Map Review assessment capabilities v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["contract", "depthCompareMaximumResolution", "methods"],
+	"properties": {
+		"contract": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "version"],
+			"properties": {
+				"name": { "const": "ue-shed-review-assessment-capabilities" },
+				"version": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["major", "minor"],
+					"properties": {
+						"major": { "const": 1 },
+						"minor": { "const": 0 }
+					}
+				}
+			}
+		},
+		"depthCompareMaximumResolution": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["width", "height"],
+			"properties": {
+				"width": { "type": "integer", "minimum": 1 },
+				"height": { "type": "integer", "minimum": 1 }
+			}
+		},
+		"methods": {
+			"type": "array",
+			"minItems": 1,
+			"maxItems": 16,
+			"items": { "$ref": "#/$defs/methodCapability" }
+		}
+	},
+	"$defs": {
+		"effectiveMethod": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["method", "version"],
+			"properties": {
+				"method": { "enum": ["ray_samples", "subject_mask", "depth_compare"] },
+				"version": { "type": "integer", "minimum": 1 }
+			}
+		},
+		"methodCapability": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["requestedMethod", "status", "effectiveMethod", "limitations"],
+					"properties": {
+						"requestedMethod": {
+							"enum": ["automatic", "ray_samples", "subject_mask", "depth_compare"]
+						},
+						"status": { "const": "supported" },
+						"effectiveMethod": { "$ref": "#/$defs/effectiveMethod" },
+						"limitations": {
+							"type": "array",
+							"maxItems": 8,
+							"items": { "type": "string" }
+						}
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["requestedMethod", "status", "reason"],
+					"properties": {
+						"requestedMethod": {
+							"enum": ["automatic", "ray_samples", "subject_mask", "depth_compare"]
+						},
+						"status": { "const": "unsupported" },
+						"reason": { "type": "string", "minLength": 1 }
+					}
+				}
+			]
+		}
+	}
+}

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

@@ -4,15 +4,7 @@
 	"title": "UE Shed Map Review capture request v1",
 	"type": "object",
 	"additionalProperties": false,
-	"required": [
-		"contract",
-		"operationId",
-		"viewId",
-		"expectedMapPath",
-		"subject",
-		"approvedPose",
-		"resolution"
-	],
+	"required": ["contract", "operationId", "viewId", "expectedMapPath", "subject", "resolution"],
 	"properties": {
 		"contract": {
 			"type": "object",
@@ -26,7 +18,7 @@
 					"required": ["major", "minor"],
 					"properties": {
 						"major": { "const": 1 },
-						"minor": { "type": "integer", "minimum": 0 }
+						"minor": { "type": "integer", "minimum": 0, "maximum": 4 }
 					}
 				}
 			}
@@ -35,14 +27,27 @@
 		"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 }
-			}
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["kind", "actorPath"],
+					"properties": {
+						"kind": { "const": "actor_path" },
+						"actorPath": { "type": "string", "minLength": 1 },
+						"diagnosticLabel": { "type": "string", "minLength": 1 }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["kind", "bounds"],
+					"properties": {
+						"kind": { "const": "oriented_bounds" },
+						"bounds": { "$ref": "#/$defs/bounds" }
+					}
+				}
+			]
 		},
 		"approvedPose": {
 			"type": "object",
@@ -64,8 +69,39 @@
 				"width": { "type": "integer", "minimum": 160, "maximum": 3840 },
 				"height": { "type": "integer", "minimum": 90, "maximum": 2160 }
 			}
-		}
+		},
+		"assessment": { "$ref": "#/$defs/assessment" },
+		"clearCompanion": { "$ref": "#/$defs/clearCompanion" },
+		"viewpoint": { "$ref": "#/$defs/viewpoint" }
 	},
+	"allOf": [
+		{
+			"if": {
+				"properties": {
+					"contract": {
+						"properties": {
+							"version": { "properties": { "minor": { "enum": [2, 3, 4] } } }
+						}
+					}
+				}
+			},
+			"then": { "required": ["assessment", "viewpoint"] },
+			"else": { "required": ["approvedPose"] }
+		},
+		{
+			"if": {
+				"properties": {
+					"contract": {
+						"properties": {
+							"version": { "properties": { "minor": { "const": 4 } } }
+						}
+					}
+				}
+			},
+			"then": { "required": ["clearCompanion"] },
+			"else": { "not": { "required": ["clearCompanion"] } }
+		}
+	],
 	"$defs": {
 		"safeId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
 		"vector": {
@@ -87,6 +123,124 @@
 				"yaw": { "type": "number" },
 				"roll": { "type": "number" }
 			}
+		},
+		"bounds": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["center", "extent", "rotation"],
+			"properties": {
+				"center": { "$ref": "#/$defs/vector" },
+				"extent": { "$ref": "#/$defs/vector" },
+				"rotation": { "$ref": "#/$defs/rotation" }
+			}
+		},
+		"assessment": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["method"],
+					"properties": { "method": { "const": "automatic" } }
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["method", "samplePreset"],
+					"properties": {
+						"method": { "const": "ray_samples" },
+						"samplePreset": { "enum": ["sparse", "standard", "dense"] }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["method"],
+					"properties": { "method": { "enum": ["subject_mask", "depth_compare"] } }
+				}
+			]
+		},
+		"clearCompanion": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["status"],
+					"properties": { "status": { "const": "not_requested" } }
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["status", "strategy"],
+					"properties": {
+						"status": { "const": "requested" },
+						"strategy": { "const": "isolate_target" }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["actors", "status", "strategy"],
+					"properties": {
+						"actors": {
+							"type": "array",
+							"minItems": 1,
+							"maxItems": 32,
+							"uniqueItems": true,
+							"items": {
+								"type": "string",
+								"minLength": 7,
+								"maxLength": 4096,
+								"pattern": "^/Game/"
+							}
+						},
+						"status": { "const": "requested" },
+						"strategy": { "const": "hide_explicit" }
+					}
+				}
+			]
+		},
+		"viewpoint": {
+			"oneOf": [
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["kind", "approvedPose"],
+					"properties": {
+						"kind": { "const": "world_fixed" },
+						"approvedPose": { "$ref": "#/$defs/pose" }
+					}
+				},
+				{
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["kind", "relativePose", "targetSnapshot"],
+					"properties": {
+						"kind": { "const": "target_relative" },
+						"relativePose": { "$ref": "#/$defs/pose" },
+						"targetSnapshot": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["location", "rotation"],
+							"properties": {
+								"location": { "$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 },
+				"projection": { "const": "perspective" },
+				"location": { "$ref": "#/$defs/vector" },
+				"rotation": { "$ref": "#/$defs/rotation" }
+			}
 		}
 	}
 }