@ue-shed/protocol 0.5.1 → 0.7.0

package/contracts/niagara/preview/v1/fixtures/scene-manifest.json

@@ -0,0 +1,108 @@
+{
+	"alphaPolicy": "opaque_scene_v1",
+	"artifacts": [
+		{
+			"bytes": 128,
+			"height": 64,
+			"index": 0,
+			"maximumRgb": 1,
+			"mimeType": "image/png",
+			"nonTransparentPixelFraction": 1,
+			"relativePath": "frames/frame_0000.png",
+			"sha256": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+			"timeSeconds": 0,
+			"width": 64,
+			"activityScore": 0.1,
+			"edgePixelFraction": 0
+		},
+		{
+			"bytes": 144,
+			"height": 64,
+			"index": 1,
+			"maximumRgb": 0.8,
+			"mimeType": "image/png",
+			"nonTransparentPixelFraction": 1,
+			"relativePath": "frames/frame_0001.png",
+			"sha256": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+			"timeSeconds": 0.5,
+			"width": 64,
+			"activityScore": 0.1,
+			"edgePixelFraction": 0
+		}
+	],
+	"camera": {
+		"aspectRatio": 1,
+		"fieldOfViewDegrees": 90,
+		"location": {
+			"x": 0,
+			"y": -200,
+			"z": 0
+		},
+		"orthoWidth": 512,
+		"projection": "perspective",
+		"rotation": {
+			"pitch": 0,
+			"roll": 0,
+			"yaw": 0
+		},
+		"usesCustomAspectRatio": false
+	},
+	"colorSpace": "srgb",
+	"contract": {
+		"name": "ue-shed-niagara-preview-run",
+		"version": {
+			"major": 1,
+			"minor": 1
+		}
+	},
+	"diagnostics": [
+		{
+			"code": "missing_material",
+			"message": "2 renderer material slots were unbound at initialization. Inspect renderer assignments and user parameters."
+		}
+	],
+	"effectiveSettings": {
+		"captureMode": "full_scene",
+		"durationSeconds": 1,
+		"frameCount": 2,
+		"frameIntervalSeconds": 0.5,
+		"height": 64,
+		"playbackFramesPerSecond": 2,
+		"simulationFramesPerSecond": 60,
+		"startSeconds": 0,
+		"width": 64,
+		"renderMode": "scene",
+		"cameraMode": "auto_fit",
+		"sceneProfile": "ground_impact",
+		"exposureCompensation": 1,
+		"cameraPadding": 1.2
+	},
+	"generatedAtUtc": "2026-08-20T00:00:01.000Z",
+	"producer": {
+		"engineVersion": "5.7.2-0+++UE5+Release-5.7",
+		"receiptContract": {
+			"name": "ue-shed-niagara-preview-receipt",
+			"version": {
+				"major": 1,
+				"minor": 1
+			}
+		}
+	},
+	"requestedSettings": {
+		"captureMode": "full_scene",
+		"durationSeconds": 1,
+		"frameCount": 2,
+		"height": 64,
+		"simulationFramesPerSecond": 60,
+		"startSeconds": 0,
+		"width": 64,
+		"renderMode": "scene",
+		"cameraMode": "auto_fit",
+		"sceneProfile": "ground_impact",
+		"exposureCompensation": 1,
+		"cameraPadding": 1.2
+	},
+	"runId": "11111111-1111-4111-8111-111111111111",
+	"status": "complete",
+	"systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
+}

package/contracts/niagara/preview/v1/fixtures/scene-receipt.json

@@ -0,0 +1,84 @@
+{
+	"missingMaterialCount": 2,
+	"alphaPolicy": "opaque_scene_v1",
+	"camera": {
+		"aspectRatio": 1,
+		"fieldOfViewDegrees": 90,
+		"location": {
+			"x": 0,
+			"y": -200,
+			"z": 0
+		},
+		"orthoWidth": 512,
+		"projection": "perspective",
+		"rotation": {
+			"pitch": 0,
+			"roll": 0,
+			"yaw": 0
+		},
+		"usesCustomAspectRatio": false
+	},
+	"colorSpace": "srgb",
+	"contract": {
+		"name": "ue-shed-niagara-preview-receipt",
+		"version": {
+			"major": 1,
+			"minor": 1
+		}
+	},
+	"effectiveSettings": {
+		"captureMode": "full_scene",
+		"durationSeconds": 1,
+		"frameCount": 2,
+		"frameIntervalSeconds": 0.5,
+		"height": 64,
+		"playbackFramesPerSecond": 2,
+		"simulationFramesPerSecond": 60,
+		"startSeconds": 0,
+		"width": 64,
+		"renderMode": "scene",
+		"cameraMode": "auto_fit",
+		"sceneProfile": "ground_impact",
+		"exposureCompensation": 1,
+		"cameraPadding": 1.2
+	},
+	"engineVersion": "5.7.2-0+++UE5+Release-5.7",
+	"frames": [
+		{
+			"index": 0,
+			"maximumRgb": 1,
+			"nonTransparentPixelFraction": 1,
+			"relativePath": "frames/frame_0000.png",
+			"timeSeconds": 0,
+			"activityScore": 0.1,
+			"edgePixelFraction": 0
+		},
+		{
+			"index": 1,
+			"maximumRgb": 0.8,
+			"nonTransparentPixelFraction": 1,
+			"relativePath": "frames/frame_0001.png",
+			"timeSeconds": 0.5,
+			"activityScore": 0.1,
+			"edgePixelFraction": 0
+		}
+	],
+	"generatedAtUtc": "2026-08-20T00:00:00.000Z",
+	"requestedSettings": {
+		"captureMode": "full_scene",
+		"durationSeconds": 1,
+		"frameCount": 2,
+		"height": 64,
+		"simulationFramesPerSecond": 60,
+		"startSeconds": 0,
+		"width": 64,
+		"renderMode": "scene",
+		"cameraMode": "auto_fit",
+		"sceneProfile": "ground_impact",
+		"exposureCompensation": 1,
+		"cameraPadding": 1.2
+	},
+	"runId": "11111111-1111-4111-8111-111111111111",
+	"status": "complete",
+	"systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
+}

package/contracts/niagara/preview/v1/fixtures/scene-request.json

@@ -0,0 +1,25 @@
+{
+	"contract": {
+		"name": "ue-shed-niagara-preview-request",
+		"version": {
+			"major": 1,
+			"minor": 1
+		}
+	},
+	"runId": "11111111-1111-4111-8111-111111111111",
+	"settings": {
+		"captureMode": "full_scene",
+		"durationSeconds": 1,
+		"frameCount": 2,
+		"height": 64,
+		"simulationFramesPerSecond": 60,
+		"startSeconds": 0,
+		"width": 64,
+		"renderMode": "scene",
+		"cameraMode": "auto_fit",
+		"sceneProfile": "ground_impact",
+		"exposureCompensation": 1,
+		"cameraPadding": 1.2
+	},
+	"systemObjectPath": "/Game/Fixture/Niagara/NS_Preview.NS_Preview"
+}

package/contracts/niagara/preview/v1/manifest.schema.json

@@ -18,7 +18,9 @@
 		"systemObjectPath"
 	],
 	"properties": {
-		"alphaPolicy": { "const": "scene_opacity_or_emissive_coverage_v1" },
+		"alphaPolicy": {
+			"enum": ["scene_opacity_or_emissive_coverage_v1", "opaque_scene_v1"]
+		},
 		"artifacts": {
 			"type": "array",
 			"minItems": 1,
@@ -37,34 +39,87 @@
 					"width"
 				],
 				"properties": {
-					"bytes": { "type": "integer", "minimum": 1 },
-					"height": { "type": "integer", "minimum": 1, "maximum": 4096 },
-					"index": { "type": "integer", "minimum": 0 },
-					"maximumRgb": { "type": "number", "minimum": 0, "maximum": 1 },
-					"mimeType": { "const": "image/png" },
-					"nonTransparentPixelFraction": { "type": "number", "minimum": 0, "maximum": 1 },
+					"bytes": {
+						"type": "integer",
+						"minimum": 1
+					},
+					"height": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 4096
+					},
+					"index": {
+						"type": "integer",
+						"minimum": 0
+					},
+					"maximumRgb": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
+					"mimeType": {
+						"const": "image/png"
+					},
+					"nonTransparentPixelFraction": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
 					"relativePath": {
 						"type": "string",
 						"pattern": "^frames/frame_[0-9]{4}\\.png$"
 					},
-					"sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
-					"timeSeconds": { "type": "number", "minimum": 0 },
-					"width": { "type": "integer", "minimum": 1, "maximum": 4096 }
+					"sha256": {
+						"type": "string",
+						"pattern": "^sha256:[0-9a-f]{64}$"
+					},
+					"timeSeconds": {
+						"type": "number",
+						"minimum": 0
+					},
+					"width": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 4096
+					},
+					"activityScore": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
+					"edgePixelFraction": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					}
 				},
 				"additionalProperties": false
 			}
 		},
-		"camera": { "$ref": "common.schema.json#/$defs/camera" },
-		"colorSpace": { "const": "srgb" },
+		"camera": {
+			"$ref": "common.schema.json#/$defs/camera"
+		},
+		"colorSpace": {
+			"const": "srgb"
+		},
 		"contract": {
 			"type": "object",
 			"required": ["name", "version"],
 			"properties": {
-				"name": { "const": "ue-shed-niagara-preview-run" },
+				"name": {
+					"const": "ue-shed-niagara-preview-run"
+				},
 				"version": {
 					"type": "object",
 					"required": ["major", "minor"],
-					"properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
+					"properties": {
+						"major": {
+							"const": 1
+						},
+						"minor": {
+							"enum": [0, 1, 2]
+						}
+					},
 					"additionalProperties": false
 				}
 			},
@@ -76,28 +131,50 @@
 				"type": "object",
 				"required": ["code", "message"],
 				"properties": {
-					"code": { "enum": ["nearly_black", "nearly_empty"] },
-					"message": { "type": "string", "minLength": 1 }
+					"code": {
+						"enum": ["nearly_black", "nearly_empty", "missing_material"]
+					},
+					"message": {
+						"type": "string",
+						"minLength": 1
+					}
 				},
 				"additionalProperties": false
 			}
 		},
-		"effectiveSettings": { "$ref": "common.schema.json#/$defs/effectiveSettings" },
-		"generatedAtUtc": { "type": "string", "minLength": 1 },
+		"effectiveSettings": {
+			"$ref": "common.schema.json#/$defs/effectiveSettings"
+		},
+		"generatedAtUtc": {
+			"type": "string",
+			"minLength": 1
+		},
 		"producer": {
 			"type": "object",
 			"required": ["engineVersion", "receiptContract"],
 			"properties": {
-				"engineVersion": { "type": "string", "minLength": 1 },
+				"engineVersion": {
+					"type": "string",
+					"minLength": 1
+				},
 				"receiptContract": {
 					"type": "object",
 					"required": ["name", "version"],
 					"properties": {
-						"name": { "const": "ue-shed-niagara-preview-receipt" },
+						"name": {
+							"const": "ue-shed-niagara-preview-receipt"
+						},
 						"version": {
 							"type": "object",
 							"required": ["major", "minor"],
-							"properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
+							"properties": {
+								"major": {
+									"const": 1
+								},
+								"minor": {
+									"enum": [0, 1, 2]
+								}
+							},
 							"additionalProperties": false
 						}
 					},
@@ -106,10 +183,18 @@
 			},
 			"additionalProperties": false
 		},
-		"requestedSettings": { "$ref": "common.schema.json#/$defs/settings" },
-		"runId": { "$ref": "common.schema.json#/$defs/runId" },
-		"status": { "const": "complete" },
-		"systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
+		"requestedSettings": {
+			"$ref": "common.schema.json#/$defs/settings"
+		},
+		"runId": {
+			"$ref": "common.schema.json#/$defs/runId"
+		},
+		"status": {
+			"const": "complete"
+		},
+		"systemObjectPath": {
+			"$ref": "common.schema.json#/$defs/systemObjectPath"
+		}
 	},
 	"additionalProperties": false
 }

package/contracts/niagara/preview/v1/progress.schema.json

@@ -0,0 +1,37 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schemaVersion", "runId", "phase", "completedFrames", "totalFrames", "elapsedMs"],
+	"properties": {
+		"schemaVersion": {
+			"const": 1
+		},
+		"runId": {
+			"type": "string",
+			"minLength": 1
+		},
+		"phase": {
+			"enum": [
+				"initializing",
+				"compiling",
+				"camera_fitting",
+				"capturing",
+				"writing_receipt",
+				"completed"
+			]
+		},
+		"completedFrames": {
+			"type": "integer",
+			"minimum": 0
+		},
+		"totalFrames": {
+			"type": "integer",
+			"minimum": 1
+		},
+		"elapsedMs": {
+			"type": "number",
+			"minimum": 0
+		}
+	}
+}

package/contracts/niagara/preview/v1/receipt.schema.json

@@ -17,25 +17,49 @@
 		"systemObjectPath"
 	],
 	"properties": {
-		"alphaPolicy": { "const": "scene_opacity_or_emissive_coverage_v1" },
-		"camera": { "$ref": "common.schema.json#/$defs/camera" },
-		"colorSpace": { "const": "srgb" },
+		"missingMaterialCount": {
+			"type": "integer",
+			"minimum": 0
+		},
+		"alphaPolicy": {
+			"enum": ["scene_opacity_or_emissive_coverage_v1", "opaque_scene_v1"]
+		},
+		"camera": {
+			"$ref": "common.schema.json#/$defs/camera"
+		},
+		"colorSpace": {
+			"const": "srgb"
+		},
 		"contract": {
 			"type": "object",
 			"required": ["name", "version"],
 			"properties": {
-				"name": { "const": "ue-shed-niagara-preview-receipt" },
+				"name": {
+					"const": "ue-shed-niagara-preview-receipt"
+				},
 				"version": {
 					"type": "object",
 					"required": ["major", "minor"],
-					"properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
+					"properties": {
+						"major": {
+							"const": 1
+						},
+						"minor": {
+							"enum": [0, 1, 2]
+						}
+					},
 					"additionalProperties": false
 				}
 			},
 			"additionalProperties": false
 		},
-		"effectiveSettings": { "$ref": "common.schema.json#/$defs/effectiveSettings" },
-		"engineVersion": { "type": "string", "minLength": 1 },
+		"effectiveSettings": {
+			"$ref": "common.schema.json#/$defs/effectiveSettings"
+		},
+		"engineVersion": {
+			"type": "string",
+			"minLength": 1
+		},
 		"frames": {
 			"type": "array",
 			"minItems": 1,
@@ -49,23 +73,58 @@
 					"timeSeconds"
 				],
 				"properties": {
-					"index": { "type": "integer", "minimum": 0 },
-					"maximumRgb": { "type": "number", "minimum": 0, "maximum": 1 },
-					"nonTransparentPixelFraction": { "type": "number", "minimum": 0, "maximum": 1 },
+					"index": {
+						"type": "integer",
+						"minimum": 0
+					},
+					"maximumRgb": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
+					"nonTransparentPixelFraction": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
 					"relativePath": {
 						"type": "string",
 						"pattern": "^frames/frame_[0-9]{4}\\.png$"
 					},
-					"timeSeconds": { "type": "number", "minimum": 0 }
+					"timeSeconds": {
+						"type": "number",
+						"minimum": 0
+					},
+					"activityScore": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					},
+					"edgePixelFraction": {
+						"type": "number",
+						"minimum": 0,
+						"maximum": 1
+					}
 				},
 				"additionalProperties": false
 			}
 		},
-		"generatedAtUtc": { "type": "string", "minLength": 1 },
-		"requestedSettings": { "$ref": "common.schema.json#/$defs/settings" },
-		"runId": { "$ref": "common.schema.json#/$defs/runId" },
-		"status": { "const": "complete" },
-		"systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
+		"generatedAtUtc": {
+			"type": "string",
+			"minLength": 1
+		},
+		"requestedSettings": {
+			"$ref": "common.schema.json#/$defs/settings"
+		},
+		"runId": {
+			"$ref": "common.schema.json#/$defs/runId"
+		},
+		"status": {
+			"const": "complete"
+		},
+		"systemObjectPath": {
+			"$ref": "common.schema.json#/$defs/systemObjectPath"
+		}
 	},
 	"additionalProperties": false
 }

package/contracts/niagara/preview/v1/request.schema.json

@@ -8,19 +8,34 @@
 			"type": "object",
 			"required": ["name", "version"],
 			"properties": {
-				"name": { "const": "ue-shed-niagara-preview-request" },
+				"name": {
+					"const": "ue-shed-niagara-preview-request"
+				},
 				"version": {
 					"type": "object",
 					"required": ["major", "minor"],
-					"properties": { "major": { "const": 1 }, "minor": { "const": 0 } },
+					"properties": {
+						"major": {
+							"const": 1
+						},
+						"minor": {
+							"enum": [0, 1, 2]
+						}
+					},
 					"additionalProperties": false
 				}
 			},
 			"additionalProperties": false
 		},
-		"runId": { "$ref": "common.schema.json#/$defs/runId" },
-		"settings": { "$ref": "common.schema.json#/$defs/settings" },
-		"systemObjectPath": { "$ref": "common.schema.json#/$defs/systemObjectPath" }
+		"runId": {
+			"$ref": "common.schema.json#/$defs/runId"
+		},
+		"settings": {
+			"$ref": "common.schema.json#/$defs/settings"
+		},
+		"systemObjectPath": {
+			"$ref": "common.schema.json#/$defs/systemObjectPath"
+		}
 	},
 	"additionalProperties": false
 }

package/contracts/niagara/preview/v1/session.md

@@ -0,0 +1,25 @@
+# Niagara session transport v1
+
+This local filesystem transport carries the existing preview request contract unchanged.
+It is available only to trusted process-owning hosts. Every launch uses a new private
+directory. It is not a network protocol or a way to attach to arbitrary editor processes.
+
+- Producer readiness: atomically publish `ready.json` containing
+  `{ "protocol": "ue-shed-niagara-session.v1" }`.
+- Submit: atomically rename a complete request to `<runId>.request.json`. The lowercase
+  UUID v4 filename must match the request's `runId`. IDs are never reused in a session.
+- Result: atomically publish `<runId>.result.json` containing
+  `{ "protocol": "ue-shed-niagara-session.v1", "runId": "<UUID>", "exitCode": 0 }`.
+  Exit codes are integers 0–255 with the same meaning as single-request commandlet exits.
+  A result is at most 4096 bytes. Success still requires validation of the existing
+  producer receipt and PNG artifacts; this result alone does not authorize publication.
+- Cancel: the host creates `<runId>.cancel`. The producer checks before work and between
+  output frames. Timeouts or interrupted consumers leave this marker.
+- Retire: a `stop` file asks the producer to exit between requests. The supervising host
+  writes `closed` on process exit or forced termination. Consumers accept already-completed
+  matching results, but fail pending work when `closed` appears.
+
+The producer handles requests serially. It destroys each scene and collects garbage before
+publishing its result. It exits after 300 requests or 900 seconds without work and removes
+`ready.json`. The host must stop the process before any source revision changes. The host's
+process tree—not a stored PID—is the authority for forced cleanup.

package/contracts/observatory/v1/actor-metadata.schema.json

@@ -0,0 +1,33 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [],
+	"properties": {
+		"actorGuid": {
+			"type": "string",
+			"pattern": "^[0-9A-Fa-f]{32}$"
+		},
+		"classPath": {
+			"type": "string",
+			"minLength": 1
+		},
+		"folderPath": {
+			"type": "string"
+		},
+		"levelPackage": {
+			"type": "string",
+			"minLength": 1
+		},
+		"tags": {
+			"type": "array",
+			"items": {
+				"type": "string"
+			},
+			"maxItems": 256
+		},
+		"tagsTruncated": {
+			"type": "boolean"
+		}
+	}
+}