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

package/contracts/cameras/review/v1/fixtures/capture-assessed-v2.json

@@ -0,0 +1,56 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 2 }
+	},
+	"status": "captured",
+	"operationId": "capture-assessed-v2",
+	"viewId": "structure-follow",
+	"resolvedSubject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+		"transform": {
+			"location": { "x": 100, "y": 200, "z": 300 },
+			"rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
+		}
+	},
+	"effectiveWorldPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 70,
+		"projection": "perspective",
+		"location": { "x": 1200, "y": -900, "z": 700 },
+		"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+	},
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-assessed-v2/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 14.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 },
+		"margins": { "left": 0.2, "right": 0.2, "top": 0.2, "bottom": 0.2 }
+	},
+	"visibility": {
+		"status": "assessed",
+		"classification": "partial",
+		"method": { "method": "ray_samples", "version": 1 },
+		"visibleFraction": 0.6666666666666666,
+		"sampleCount": 9,
+		"assessmentDurationMs": 0.25,
+		"limitations": ["Collision rays are diagnostic and may differ from rendered visibility."],
+		"occluders": [
+			{
+				"confidence": 0.3333333333333333,
+				"locator": {
+					"kind": "actor_path",
+					"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewOccluder"
+				},
+				"reason": "The actor blocked one or more bounded visibility rays."
+			}
+		]
+	}
+}

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

@@ -0,0 +1,55 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 3 }
+	},
+	"status": "captured",
+	"operationId": "capture-assessed",
+	"viewId": "structure-follow",
+	"resolvedSubject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+		"transform": {
+			"location": { "x": 100, "y": 200, "z": 300 },
+			"rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
+		}
+	},
+	"effectiveWorldPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 70,
+		"projection": "perspective",
+		"location": { "x": 1200, "y": -900, "z": 700 },
+		"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+	},
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-assessed/pure.png",
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 14.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 },
+		"margins": { "left": 0.2, "right": 0.2, "top": 0.2, "bottom": 0.2 }
+	},
+	"visibility": {
+		"status": "assessed",
+		"method": { "method": "ray_samples", "version": 1 },
+		"visibleFraction": 0.6666666666666666,
+		"sampleCount": 9,
+		"assessmentDurationMs": 0.25,
+		"limitations": ["Collision rays are diagnostic and may differ from rendered visibility."],
+		"occluders": [
+			{
+				"confidence": 0.3333333333333333,
+				"locator": {
+					"kind": "actor_path",
+					"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewOccluder"
+				},
+				"reason": "The actor blocked one or more bounded visibility rays."
+			}
+		]
+	}
+}

package/contracts/cameras/review/v1/fixtures/capture-clear-failed.json

@@ -0,0 +1,62 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 4 }
+	},
+	"status": "captured",
+	"operationId": "capture-clear-failed",
+	"viewId": "structure-clear",
+	"resolvedSubject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+		"transform": {
+			"location": { "x": 100, "y": 200, "z": 300 },
+			"rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
+		}
+	},
+	"effectiveWorldPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 70,
+		"projection": "perspective",
+		"location": { "x": 1200, "y": -900, "z": 700 },
+		"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+	},
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagedArtifacts": [
+		{
+			"variant": "pure",
+			"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-clear-failed/pure.png"
+		}
+	],
+	"clearCompanion": {
+		"status": "failed",
+		"strategy": "hide_explicit",
+		"interventions": [],
+		"failure": {
+			"code": "clear_actor_not_found",
+			"message": "A requested Clear actor was not found.",
+			"recovery": "Update the explicit Clear actors and retry.",
+			"retrySafe": true
+		},
+		"restoration": {
+			"status": "restored",
+			"method": "transient_capture_component_lists"
+		}
+	},
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 15.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 },
+		"margins": { "left": 0.2, "right": 0.2, "top": 0.2, "bottom": 0.2 }
+	},
+	"visibility": {
+		"status": "not_assessed",
+		"reason": "Clear preparation failed after Pure capture.",
+		"limitations": []
+	}
+}

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

@@ -0,0 +1,72 @@
+{
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 4 }
+	},
+	"status": "captured",
+	"operationId": "capture-clear",
+	"viewId": "structure-clear",
+	"resolvedSubject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject",
+		"transform": {
+			"location": { "x": 100, "y": 200, "z": 300 },
+			"rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
+		}
+	},
+	"effectiveWorldPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 70,
+		"projection": "perspective",
+		"location": { "x": 1200, "y": -900, "z": 700 },
+		"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+	},
+	"mapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"stagedArtifacts": [
+		{
+			"variant": "pure",
+			"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-clear/pure.png"
+		},
+		{
+			"variant": "clear",
+			"stagingPath": "C:/fixture/Saved/UEShed/ReviewStaging/capture-clear/clear.png"
+		}
+	],
+	"clearCompanion": {
+		"status": "captured",
+		"strategy": "hide_explicit",
+		"interventions": [
+			{
+				"type": "hide_actor_components",
+				"target": {
+					"kind": "actor_path",
+					"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewOccluder"
+				}
+			}
+		],
+		"restoration": {
+			"status": "restored",
+			"method": "transient_capture_component_lists"
+		}
+	},
+	"width": 1280,
+	"height": 720,
+	"captureDurationMs": 22.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 },
+		"margins": { "left": 0.2, "right": 0.2, "top": 0.2, "bottom": 0.2 }
+	},
+	"visibility": {
+		"status": "assessed",
+		"method": { "method": "depth_compare", "version": 1 },
+		"visibleFraction": 0.4,
+		"sampleCount": 6400,
+		"assessmentDurationMs": 1.5,
+		"limitations": ["Bounded depth comparison."],
+		"occluders": []
+	}
+}

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

@@ -0,0 +1,29 @@
+{
+	"assessment": { "method": "automatic" },
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 3 }
+	},
+	"operationId": "33333333-3333-4333-8333-333333333333",
+	"viewId": "loading-area",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"subject": {
+		"kind": "oriented_bounds",
+		"bounds": {
+			"center": { "x": 0, "y": 0, "z": 200 },
+			"extent": { "x": 600, "y": 400, "z": 200 },
+			"rotation": { "pitch": 0, "yaw": 30, "roll": 0 }
+		}
+	},
+	"viewpoint": {
+		"kind": "world_fixed",
+		"approvedPose": {
+			"aspectRatio": "16:9",
+			"fieldOfViewDegrees": 70,
+			"projection": "perspective",
+			"location": { "x": 1200, "y": -900, "z": 700 },
+			"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+		}
+	},
+	"resolution": { "width": 1280, "height": 720 }
+}

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

@@ -0,0 +1,30 @@
+{
+	"assessment": { "method": "automatic" },
+	"clearCompanion": {
+		"status": "requested",
+		"strategy": "hide_explicit",
+		"actors": ["/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewOccluder"]
+	},
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 4 }
+	},
+	"operationId": "33333333-3333-4333-8333-333333333333",
+	"viewId": "structure-clear",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"subject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject"
+	},
+	"viewpoint": {
+		"kind": "world_fixed",
+		"approvedPose": {
+			"aspectRatio": "16:9",
+			"fieldOfViewDegrees": 70,
+			"projection": "perspective",
+			"location": { "x": 1200, "y": -900, "z": 700 },
+			"rotation": { "pitch": -20, "yaw": 145, "roll": 0 }
+		}
+	},
+	"resolution": { "width": 1280, "height": 720 }
+}

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

@@ -0,0 +1,29 @@
+{
+	"assessment": { "method": "ray_samples", "samplePreset": "standard" },
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": { "major": 1, "minor": 3 }
+	},
+	"operationId": "22222222-2222-4222-8222-222222222222",
+	"viewId": "structure-follow",
+	"expectedMapPath": "/Game/Fixture/Cameras/L_CameraLoad",
+	"subject": {
+		"kind": "actor_path",
+		"actorPath": "/Game/Fixture/Cameras/L_CameraLoad.L_CameraLoad:PersistentLevel.ReviewSubject"
+	},
+	"viewpoint": {
+		"kind": "target_relative",
+		"relativePose": {
+			"aspectRatio": "16:9",
+			"fieldOfViewDegrees": 70,
+			"projection": "perspective",
+			"location": { "x": -900, "y": 0, "z": 300 },
+			"rotation": { "pitch": -15, "yaw": 0, "roll": 0 }
+		},
+		"targetSnapshot": {
+			"location": { "x": 100, "y": 200, "z": 300 },
+			"rotation": { "pitch": 0, "yaw": 45, "roll": 0 }
+		}
+	},
+	"resolution": { "width": 1280, "height": 720 }
+}

package/contracts/cameras/review/v1/fixtures/invalid-assessment-capabilities-supported-without-effective-method.json

@@ -0,0 +1,14 @@
+{
+	"contract": {
+		"name": "ue-shed-review-assessment-capabilities",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"depthCompareMaximumResolution": { "width": 320, "height": 180 },
+	"methods": [
+		{
+			"requestedMethod": "automatic",
+			"status": "supported",
+			"limitations": []
+		}
+	]
+}

package/contracts/scenarios/live/v1/README.md

@@ -0,0 +1,9 @@
+# Live scenario execution v1 fixtures
+
+These JSON fixtures freeze the language-neutral control-plane values shared by
+`@ue-shed/scenarios` and the optional `UEShedScenarios` Unreal plugin. The Effect schemas in
+`packages/scenarios/src/live.ts` own validation; conformance tests decode and re-encode every
+fixture without loss.
+
+Version 1 supports only the deterministic Movement Gym PIE slice, `pre_evaluation` input,
+Move/Jump/Interact, one blocking `landing_ready` wait, one `cache_open` probe, and bounded evidence.

package/contracts/scenarios/live/v1/fixtures/cancel-accepted.json

@@ -0,0 +1,8 @@
+{
+	"_tag": "Accepted",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"runId": "run-live-1"
+}

package/contracts/scenarios/live/v1/fixtures/execution-request.json

@@ -0,0 +1,44 @@
+{
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"actions": [
+		{
+			"actionId": "Move",
+			"actionPath": "/Game/Fixture/Input/IA_Move",
+			"keyframes": [
+				{ "atMs": 250, "value": { "_tag": "Axis2D", "x": 0, "y": 1 } },
+				{ "atMs": 1000, "value": { "_tag": "Axis2D", "x": 0, "y": 0 } }
+			],
+			"valueType": "Axis2D"
+		},
+		{
+			"actionId": "Jump",
+			"actionPath": "/Game/Fixture/Input/IA_Jump",
+			"keyframes": [
+				{ "atMs": 1200, "value": { "_tag": "Boolean", "value": true } },
+				{ "atMs": 1250, "value": { "_tag": "Boolean", "value": false } }
+			],
+			"valueType": "Boolean"
+		},
+		{
+			"actionId": "Interact",
+			"actionPath": "/Game/Fixture/Input/IA_Interact",
+			"keyframes": [
+				{ "atMs": 5200, "value": { "_tag": "Boolean", "value": true } },
+				{ "atMs": 5250, "value": { "_tag": "Boolean", "value": false } }
+			],
+			"valueType": "Boolean"
+		}
+	],
+	"durationMs": 9216,
+	"evidenceLimit": 3,
+	"expectedPieSessionId": "pie-session-1",
+	"injectionLayer": "pre_evaluation",
+	"liveInputPolicy": "isolated",
+	"mapPath": "/Game/Fixture/Scenarios/L_MovementGym",
+	"probe": { "atMs": 5580, "condition": "cache_open" },
+	"scenarioId": "scenario_movement-gym_014",
+	"wait": { "atMs": 4100, "condition": "landing_ready", "timeoutMs": 1250 }
+}

package/contracts/scenarios/live/v1/fixtures/prepare-prepared.json

@@ -0,0 +1,9 @@
+{
+	"_tag": "Prepared",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"mapPath": "/Game/Fixture/Scenarios/L_MovementGym",
+	"scenarioId": "scenario_movement-gym_014"
+}

package/contracts/scenarios/live/v1/fixtures/start-accepted.json

@@ -0,0 +1,10 @@
+{
+	"_tag": "Accepted",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"pieSessionId": "pie-session-1",
+	"runId": "run-live-1",
+	"state": "accepted"
+}

package/contracts/scenarios/live/v1/fixtures/status-active.json

@@ -0,0 +1,11 @@
+{
+	"_tag": "Active",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"gameTimeMs": 4100,
+	"pieSessionId": "pie-session-1",
+	"runId": "run-live-1",
+	"state": "waiting"
+}

package/contracts/scenarios/live/v1/fixtures/status-rejected-stale.json

@@ -0,0 +1,10 @@
+{
+	"_tag": "Rejected",
+	"code": "stale_session",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"message": "The PIE session changed while the run was active.",
+	"recovery": "Start a fresh run against the current PIE session."
+}

package/contracts/scenarios/live/v1/fixtures/status-terminal-cancelled.json

@@ -0,0 +1,33 @@
+{
+	"_tag": "Terminal",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"result": {
+		"schemaVersion": 1,
+		"id": "run-live-cancelled",
+		"scenarioId": "scenario_movement-gym_014",
+		"label": "Movement Gym live run",
+		"status": "cancelled",
+		"recordedAt": "2026-08-11T00:00:00.000Z",
+		"durationMs": 2100,
+		"engineVersion": "5.7",
+		"world": "L_MovementGym:PersistentLevel",
+		"evidence": [],
+		"divergences": [],
+		"pieSessionId": "pie-session-1",
+		"lifecycle": [
+			{ "state": "accepted", "atGameTimeMs": 0 },
+			{ "state": "isolating", "atGameTimeMs": 0 },
+			{ "state": "running", "atGameTimeMs": 0 },
+			{ "state": "cancelling", "atGameTimeMs": 2100 },
+			{ "state": "terminal", "atGameTimeMs": 2100 }
+		],
+		"inputIsolation": {
+			"established": true,
+			"restored": true,
+			"method": "slate_input_preprocessor"
+		}
+	}
+}

package/contracts/scenarios/live/v1/fixtures/status-terminal-missing-divergence.json

@@ -0,0 +1,54 @@
+{
+	"_tag": "Terminal",
+	"contract": {
+		"name": "ue-shed-scenario-execution",
+		"version": { "major": 1, "minor": 0 }
+	},
+	"result": {
+		"schemaVersion": 1,
+		"id": "run-live-1",
+		"scenarioId": "scenario_movement-gym_014",
+		"label": "Movement Gym live run",
+		"status": "completed_with_divergence",
+		"recordedAt": "2026-08-11T00:00:00.000Z",
+		"durationMs": 9216,
+		"engineVersion": "5.7",
+		"world": "L_MovementGym:PersistentLevel",
+		"evidence": [
+			{
+				"id": "evidence_cache_open",
+				"markerId": "marker_cache_state",
+				"atMs": 5580,
+				"type": "world_state",
+				"label": "Cache state",
+				"summary": "The fixture state provider returned no cache observation.",
+				"status": "missing"
+			}
+		],
+		"divergences": [
+			{
+				"id": "divergence_wait_timing",
+				"atMs": 4100,
+				"severity": "warning",
+				"source": "timing",
+				"expected": "landing_ready within 1250 ms",
+				"observed": "landing_ready after 1310 ms",
+				"explanation": "The blocking condition exceeded its expected game-time tolerance."
+			}
+		],
+		"pieSessionId": "pie-session-1",
+		"lifecycle": [
+			{ "state": "accepted", "atGameTimeMs": 0 },
+			{ "state": "isolating", "atGameTimeMs": 0 },
+			{ "state": "running", "atGameTimeMs": 0 },
+			{ "state": "waiting", "atGameTimeMs": 4100 },
+			{ "state": "running", "atGameTimeMs": 4100 },
+			{ "state": "terminal", "atGameTimeMs": 9216 }
+		],
+		"inputIsolation": {
+			"established": true,
+			"restored": true,
+			"method": "slate_input_preprocessor"
+		}
+	}
+}

package/contracts/uasset-io/v1/README.md

@@ -0,0 +1,34 @@
+# UAsset IO protocol v1
+
+The checked-in JSON Schemas in this directory are the language-neutral authority for the UAsset
+process seam. A caller writes one request to the uasset protocol command's stdin. The command writes
+one NDJSON event stream to stdout.
+
+Version 1 carries the complete request envelope, stream-control events, and typed result frames.
+Every frame carries the same contract, requestId, and sequence. A supported request begins with
+accepted and ends with exactly one terminal event. Sequence is contiguous from zero; completed, failed,
+and rejected are terminal. An explicitly supplied empty paths array means zero work and must not
+select a project root.
+
+Minor version 1.1 adds bounded Project Index operations (`project_index_status`,
+`project_index_refresh`, `project_index_rebuild`, `project_index_query`) and their typed result
+frames. Version 1.0 operations and the cumulative meaning of `maximumOutputBytes` remain unchanged.
+Paired TypeScript and native workers negotiate additive operations; a worker that cannot decode an
+operation rejects it before `accepted`.
+
+Result frames use an explicit result kind. Generic inspection, authoring, scan, compact text,
+compact texture, and saved-world values each have a named schema; there is no untyped result field.
+The shared inspection schemas are exported from `@ue-shed/protocol` so the Effect reader and the
+Rust worker can converge on one wire shape.
+
+Expected request or operation failures use rejected or failed and exit 0. Non-zero process exits are
+reserved for failures that prevent the command from establishing or completing the protocol stream.
+Existing human command exit behavior remains unchanged.
+
+Change JSON Schema and fixtures first, keep Effect schemas conformant with
+pnpm --filter @ue-shed/protocol contract:check, then add Rust conformance coverage.
+
+The TypeScript and Rust sides both run the complete shared fixture set. TypeScript coverage is in
+`packages/protocol/src/uasset-io.test.ts`; Rust coverage is `cargo test -p uasset-io protocol`.
+Adding a result variant requires a valid fixture that both tests decode, plus an invalid fixture when
+the boundary rule needs a rejection case.