@alpsckr/unitycli 0.4.0

package/contracts/stable-session/admission-acquire-v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/admission-acquire-v1.schema.json",
+  "title": "UnityCLI internal task admission acquire v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["protocolVersion", "requestId", "instanceId", "target", "command", "rootFingerprint"],
+  "properties": {
+    "protocolVersion": { "const": 1 },
+    "requestId": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+    "target": { "enum": ["editor", "runtime"] },
+    "command": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "rootFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+  }
+}

package/contracts/stable-session/admission-response-v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/admission-response-v1.schema.json",
+  "title": "UnityCLI internal task admission response v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "requestId", "data"],
+  "properties": {
+    "ok": { "const": true },
+    "requestId": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "data": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["protocolVersion", "granted", "grantExpiresInMs", "retryAfterMs"],
+      "properties": {
+        "protocolVersion": { "const": 1 },
+        "granted": { "type": "boolean" },
+        "grantExpiresInMs": { "type": "integer", "minimum": 0, "maximum": 2000 },
+        "retryAfterMs": { "const": 100 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "granted": { "const": true } }, "required": ["granted"] },
+          "then": { "properties": { "grantExpiresInMs": { "type": "integer", "minimum": 1, "maximum": 2000 } } },
+          "else": { "properties": { "grantExpiresInMs": { "const": 0 } } }
+        }
+      ]
+    }
+  }
+}

package/contracts/stable-session/admission-revoke-v1.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/admission-revoke-v1.schema.json",
+  "title": "UnityCLI internal unconsumed admission revoke v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["protocolVersion", "requestId", "instanceId", "target", "rootFingerprint"],
+  "properties": {
+    "protocolVersion": { "const": 1 },
+    "requestId": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+    "target": { "enum": ["editor", "runtime"] },
+    "rootFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+  }
+}

package/contracts/stable-session/admission-transport-v1.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "visibility": "internal-transport-only",
+  "routes": {
+    "acquire": "POST /bridge/admission/acquire",
+    "revokeUnconsumed": "POST /bridge/admission/revoke",
+    "execute": "POST /bridge/execute"
+  },
+  "attestationHeaders": [
+    "x-unity-cli-expected-instance-id",
+    "x-unity-cli-expected-session-id",
+    "x-unity-cli-expected-target",
+    "x-unity-cli-expected-listener-id",
+    "x-unity-cli-expected-listener-generation"
+  ],
+  "grantResponseHeader": {
+    "name": "x-unity-cli-admission-token",
+    "encoding": "64 lowercase hex characters from 32 CSPRNG bytes",
+    "presentOnlyWhenGranted": true
+  },
+  "executeAndRevokeHeaders": [
+    "x-unity-cli-admission-root-id",
+    "x-unity-cli-admission-fingerprint",
+    "x-unity-cli-admission-token",
+    "x-unity-cli-admission-deadline-utc"
+  ],
+  "rules": {
+    "tokenInJsonBody": false,
+    "tokenInPublicEnvelope": false,
+    "tokenInTransactionLog": false,
+    "firstBusinessPostConsumesToken": true,
+    "consumedRootOwner": "Unity terminal owner or exact cleanup",
+    "cliMayRevokeOnlyUnconsumedGrant": true,
+    "sameRequestExactTerminalRecoveryDoesNotAcquireSlot": true
+  }
+}

package/contracts/stable-session/bridge-request-v2.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/bridge-request-v2.schema.json",
+  "title": "UnityCLI immutable Bridge request v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["protocolVersion", "requestId", "instanceId", "command", "input", "execution"],
+  "properties": {
+    "protocolVersion": { "const": 2 },
+    "requestId": { "type": "string", "pattern": "^req_[0-9a-f-]+$" },
+    "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+    "command": { "type": "string", "minLength": 1 },
+    "input": { "type": "object" },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["absoluteDeadlineUtc", "completionContractVersion", "requestDigestVersion"],
+      "properties": {
+        "absoluteDeadlineUtc": { "type": "string", "format": "date-time" },
+        "completionContractVersion": { "const": 1 },
+        "requestDigestVersion": { "const": 1 },
+        "dryRun": { "type": "boolean" }
+      }
+    }
+  }
+}

package/contracts/stable-session/canonical-path-v1-golden.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "vectors": [
+    {
+      "canonicalProjectPath": "c:\\workspace\\game",
+      "displayProjectPath": "C:\\Workspace\\Game",
+      "identityHash": "e43b51ba074c6f57a71ad29057fbab83fbad18cee55e9a7f5b7a46d394129510",
+      "instanceId": "unity-e43b51ba074c6f57a71ad29057fbab83fbad18cee55e9a7f5b7a46d394129510"
+    },
+    {
+      "canonicalProjectPath": "d:\\projects\\unity sample",
+      "displayProjectPath": "D:\\Projects\\Unity Sample",
+      "identityHash": "88ab3b12b5e5a60af3b4047aa11ff53ef64a5fac2a9426f6098ae261933c4616",
+      "instanceId": "unity-88ab3b12b5e5a60af3b4047aa11ff53ef64a5fac2a9426f6098ae261933c4616"
+    },
+    {
+      "canonicalProjectPath": "c:\\users\\developer\\project",
+      "displayProjectPath": "C:\\Users\\Developer\\Project",
+      "identityHash": "81c7409e164a24f082474cd1d7a12fc19a116965d71348049589d146a2baca00",
+      "instanceId": "unity-81c7409e164a24f082474cd1d7a12fc19a116965d71348049589d146a2baca00"
+    }
+  ]
+}

package/contracts/stable-session/completion-contract.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/completion-contract.schema.json",
+  "title": "Public Tool completion contract registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "baselineCommit", "semantics", "tools"],
+  "properties": {
+    "version": { "const": 1 },
+    "baselineCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "semantics": { "type": "string", "minLength": 1 },
+    "tools": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/toolCompletion" }
+    }
+  },
+  "$defs": {
+    "toolCompletion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["toolName", "descriptorOwner", "source", "deliveryMode", "executionClass", "completionPredicate", "proofSource", "reloadPolicy", "timeoutError", "outcomeUnknownPolicy", "asyncSignals"],
+      "properties": {
+        "toolName": { "type": "string", "minLength": 3 },
+        "descriptorOwner": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "deliveryMode": { "const": "direct-terminal" },
+        "executionClass": { "enum": ["atomic", "observed-state", "resumable", "external"] },
+        "completionPredicate": { "$ref": "#/$defs/policy" },
+        "proofSource": { "$ref": "#/$defs/policy" },
+        "reloadPolicy": { "$ref": "#/$defs/policy" },
+        "timeoutError": { "type": "string", "pattern": "^E_[A-Z0-9_]+$" },
+        "outcomeUnknownPolicy": { "$ref": "#/$defs/policy" },
+        "asyncSignals": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "description"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/contracts/stable-session/direct-call-semantics.json

@@ -0,0 +1,102 @@
+{
+  "version": 2,
+  "identity": {
+    "canonicalizationVersion": 1,
+    "instanceId": "unity-<sha256(canonical UTF-8 project path)>",
+    "selectors": ["--instance <instanceId|canonicalProjectPath|alias>", "nearest Unity project root from CWD"],
+    "forbiddenSelectors": ["PID", "port", "endpoint", "projectHash prefix", "--target", "active target", "single ready instance"]
+  },
+  "publicRoot": {
+    "requestId": "one UUID per direct public call",
+    "targetPool": "one independent pool per live Editor or Development Player session",
+    "unifiedCatalog": "one slot in every online target session whose catalog contributes to the public result",
+    "internalChildren": "catalog resolution, readiness, start, status, terminal, rebind and completion readback reuse the same root and never acquire another slot"
+  },
+  "admission": {
+    "timeout": "admissionDeadline = dispatchStartedAt + normalized --timeout-ms T",
+    "consumes": ["input parsing", "live target binding", "identity and lifecycle checks", "internal acquire polling"],
+    "polling": "one acquire at a time; each denied response sleeps an independent integer in [80,120] milliseconds",
+    "capacity": { "defaultMaxActive": 5, "defaultReopenAt": 3, "hysteresis": "5 closes; 4 remains closed; 3 reopens" },
+    "grantTtlMs": 2000,
+    "timeoutError": {
+      "code": "E_UNITY_BUSY",
+      "effectStarted": false,
+      "businessRequestSent": false,
+      "transient": true,
+      "retryAfterMs": 100
+    }
+  },
+  "request": {
+    "serialization": "one immutable UTF-8 body without BOM, frozen only after admission",
+    "executionDeadline": "executionDeadline = finalGrantObservedAt + the full normalized --timeout-ms T; it is created once",
+    "digestVersion": 1,
+    "digest": "SHA256(UTF8('unity-cli-request-v1') + NUL + UTF8(instanceId) + NUL + exactRequestBodyBytes)",
+    "admissionTokenInBody": false,
+    "redelivery": "within one direct call, exact bytes may be redelivered only while editorSessionId is unchanged; after the first mutation POST a new Editor session forbids another POST",
+    "deadlineRefreshForbidden": ["token reacquire", "status polling", "listener rebind", "terminal recovery", "completion proof"]
+  },
+  "toolExecution": {
+    "success": "terminal business success proven by the tool's unique completion contract",
+    "failure": "terminal structured failure with stable code, details and nextActions",
+    "forbiddenSuccessSignals": ["accepted", "requested", "queued", "started", "operation handle", "listener recovery", "transport success"],
+    "successEnvelopeFields": ["ok", "requestId", "data"],
+    "forbiddenSuccessFields": ["bridgeEndpoint", "port", "listenerId", "journalPhase", "transitionTimeline", "internalOperationId", "admissionToken", "activeTaskCount"]
+  },
+  "contextRead": {
+    "ordinary": {
+      "mode": "read",
+      "completion": "one complete snapshot from one validated listener generation",
+      "transitionPolicy": "wait within the execution deadline, then rerun the complete read",
+      "journal": false
+    },
+    "editor.state": {
+      "mode": "observeNow",
+      "completion": "one immediate read-only registry, Bridge and Windows observation after root admission",
+      "budgetMs": 4000,
+      "bridgeProbeBudgetMs": 3500,
+      "transitionPolicy": "never wait for state change",
+      "journal": false
+    }
+  },
+  "operability": {
+    "registry": "v3 atomic lifecycle publication for discovery and generation handoff",
+    "health": "v3 strict transport identity plus read-only in-memory main-thread pulse",
+    "publicStates": ["ready", "transitioning", "blocked", "unresponsive", "unverifiable", "offline", "conflict"],
+    "domainReload": "registry lifecycle, new listener generation, then the first main-thread pulse for that generation; no fixed-duration marker"
+  },
+  "transitionPolicy": {
+    "transparent": ["same-session domain reload", "script compile", "asset import/update", "listener restart", "endpoint fallback", "supported PlayMode transition", "waitable Unity progress"],
+    "failClosed": ["Editor session replacement after mutation POST", "external modal blocker", "identity conflict", "unverifiable identity", "unresponsive main thread", "process exit before terminal", "request ID digest conflict", "schema failure", "security failure"]
+  },
+  "directCall": {
+    "terminal": "each direct call returns a proven terminal business result or terminal structured failure",
+    "admissionBusy": "E_UNITY_BUSY before business POST proves no effect started and permits a later new root",
+    "timeout": "after grant or POST, timeout, disconnect or cross-session mutation fence returns E_EXECUTION_TIMEOUT with unknown outcome; observe business state before a new submission decision",
+    "replay": "same-session exact terminal recovery may return an existing terminal without a new slot; cross-session mutation redelivery is forbidden",
+    "slotRelease": "unconsumed grants expire or are revoked; consumed roots are released only by the Unity terminal owner or exact cleanup",
+    "audit": "business audit is a session-level append log; admission probes never enter it"
+  },
+  "host": {
+    "minimumWaitMs": "2 * T + 5000",
+    "reason": "admission may consume T and execution receives a fresh T",
+    "earlyExit": "host timeout does not prove the CLI, grant or Unity effect stopped"
+  },
+  "compile": {
+    "publicOwner": "src/tools/editor/compile.ts",
+    "privateCommands": ["internal.editor.compile.start", "internal.editor.compile.status"],
+    "inputFields": ["refresh", "path", "forceUpdate", "importRecursive", "includeWarnings"],
+    "forbiddenInputFields": ["waitReady"],
+    "proof": "owned CompilationPipeline cycle terminal, zero compiler errors, import/compile/reload stable and Editor ready",
+    "diagnostics": ["CompilationPipeline.assemblyCompilationFinished", "CompilationPipeline.compilationFinished"],
+    "errors": ["E_UNITY_COMPILE_FAILED", "E_UNITY_COMPILE_REQUIRES_EDIT_MODE", "E_COMPILE_CYCLE_UNATTRIBUTED", "E_EXECUTION_TIMEOUT", "E_UNITY_TRANSITION_TIMEOUT"]
+  },
+  "errors": [
+    "E_INSTANCE_REQUIRED", "E_INSTANCE_NOT_FOUND", "E_INSTANCE_NOT_RUNNING", "E_INSTANCE_PROJECT_MISMATCH",
+    "E_INSTANCE_IDENTITY_MISMATCH", "E_INSTANCE_PATH_UNAVAILABLE", "E_INSTANCE_REMOTE_PATH_UNSUPPORTED",
+    "E_INSTANCE_PATH_CASE_SENSITIVE_UNSUPPORTED", "E_INSTANCE_CONFLICT", "E_INSTANCE_UNVERIFIABLE",
+    "E_UNITY_UNRESPONSIVE", "E_UNITY_BLOCKED", "E_UNITY_BUSY", "E_UNITY_TRANSITION_TIMEOUT",
+    "E_EXECUTION_TIMEOUT", "E_QUEUE_START_TIMEOUT", "E_EDITOR_SESSION_REPLACED", "E_TOOL_COMPLETION_PROOF_INVALID",
+    "E_REQUEST_ID_REUSED", "E_UNITY_COMPILE_FAILED", "E_UNITY_COMPILE_REQUIRES_EDIT_MODE",
+    "E_COMPILE_CYCLE_UNATTRIBUTED", "E_OBSOLETE_LOCAL_STATE"
+  ]
+}

package/contracts/stable-session/editor-state.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/editor-state.schema.json",
+  "title": "editor.state public observation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["identity", "session", "status", "state", "progress", "blockers", "observation"],
+  "properties": {
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instanceId", "canonicalProjectPath", "displayProjectPath"],
+      "properties": {
+        "instanceId": { "type": "string" },
+        "canonicalProjectPath": { "type": "string" },
+        "displayProjectPath": { "type": "string" }
+      }
+    },
+    "session": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["known", "editorSessionId"],
+      "properties": {
+        "known": { "type": "boolean" },
+        "editorSessionId": { "type": ["string", "null"] }
+      }
+    },
+    "status": { "enum": ["ready", "transitioning", "blocked", "unresponsive", "unverifiable", "offline", "conflict"] },
+    "state": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["compile", "import", "build", "playMode", "prefabStage", "activeScene", "runtime"],
+      "properties": {
+        "compile": { "$ref": "#/$defs/observedField" },
+        "import": { "$ref": "#/$defs/observedField" },
+        "build": { "$ref": "#/$defs/observedField" },
+        "playMode": { "$ref": "#/$defs/observedField" },
+        "prefabStage": { "$ref": "#/$defs/observedField" },
+        "activeScene": { "$ref": "#/$defs/observedField" },
+        "runtime": { "$ref": "#/$defs/observedField" }
+      }
+    },
+    "progress": { "type": "array", "items": { "$ref": "#/$defs/progress" } },
+    "blockers": { "type": "array", "items": { "$ref": "#/$defs/blocker" } },
+    "observation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["freshness"],
+      "properties": {
+        "freshness": { "enum": ["live", "fresh", "stale", "unknown"] }
+      }
+    }
+  },
+  "$defs": {
+    "progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "title", "canWait", "source"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "title": { "type": "string" },
+        "value": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
+        "canWait": { "type": "boolean" },
+        "source": { "enum": ["unity", "registry"] }
+      }
+    },
+    "blocker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "dialogId", "title", "message", "buttons", "requiresUserAction", "source", "confidence"],
+      "properties": {
+        "type": { "const": "dialog" },
+        "dialogId": { "type": "string", "minLength": 1 },
+        "title": { "type": "string" },
+        "message": { "type": "string" },
+        "buttons": { "type": "array", "items": { "type": "string" } },
+        "requiresUserAction": { "const": true },
+        "source": { "const": "windows-ui" },
+        "confidence": { "const": "exact" }
+      }
+    },
+    "observedField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["known"],
+      "properties": {
+        "known": { "type": "boolean" },
+        "value": { "x-unityCliAnyJson": true }
+      }
+    }
+  }
+}

package/contracts/stable-session/health-v3.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/health-v3.schema.json",
+  "title": "UnityCLI Bridge health identity v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "target", "instanceId", "canonicalProjectPath", "canonicalizationVersion", "sessionId", "listenerId", "listenerGeneration", "actualPort", "buildStamp", "mainThread"],
+  "properties": {
+    "version": { "const": 3 },
+    "target": { "enum": ["editor", "runtime"] },
+    "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+    "canonicalProjectPath": { "type": "string", "minLength": 3 },
+    "canonicalizationVersion": { "const": 1 },
+    "sessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+    "editorSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+    "runtimeSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+    "listenerId": { "type": "string", "pattern": "^listener-[0-9a-f]{32}$" },
+    "listenerGeneration": { "type": "integer", "minimum": 1 },
+    "actualPort": { "type": "integer", "minimum": 1024, "maximum": 65535 },
+    "buildStamp": { "type": "string", "minLength": 1 },
+    "buildId": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$" },
+    "mainThread": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["observed", "sequence", "ageMs", "listenerGeneration", "lifecycle"],
+      "properties": {
+        "observed": { "type": "boolean" },
+        "sequence": { "type": "integer", "minimum": 0 },
+        "ageMs": { "type": ["integer", "null"], "minimum": 0 },
+        "listenerGeneration": { "type": "integer", "minimum": 1 },
+        "lifecycle": { "enum": ["ready", "transitioning", "blocked", "domain-reloading", "compiling", "importing", "building", "playmode-changing"] }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "properties": { "target": { "const": "editor" } },
+      "required": ["editorSessionId"],
+      "not": { "anyOf": [{ "required": ["runtimeSessionId"] }, { "required": ["buildId"] }] }
+    },
+    {
+      "properties": { "target": { "const": "runtime" } },
+      "required": ["runtimeSessionId", "buildId"],
+      "not": { "required": ["editorSessionId"] }
+    }
+  ]
+}

package/contracts/stable-session/instance-registry-v3.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unitycli.local/contracts/stable-session/instance-registry-v3.schema.json",
+  "title": "UnityCLI instance registry v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "revision", "canonicalizationVersion", "identity", "sessions", "publishedAt"],
+  "properties": {
+    "version": { "const": 3 },
+    "revision": { "type": "integer", "minimum": 0 },
+    "canonicalizationVersion": { "const": 1 },
+    "identity": { "$ref": "#/$defs/identity" },
+    "sessions": { "type": "array", "items": { "$ref": "#/$defs/session" } },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["instanceId", "canonicalProjectPath", "displayProjectPath"],
+      "properties": {
+        "instanceId": { "type": "string", "pattern": "^unity-[0-9a-f]{64}$" },
+        "canonicalProjectPath": { "type": "string", "minLength": 3 },
+        "displayProjectPath": { "type": "string", "minLength": 3 }
+      }
+    },
+    "session": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "sessionId", "processId", "processStartedAt", "publishedAt", "publicationSequence", "lifecycle", "lastUnitySnapshot", "listener", "progress", "blockers", "buildStamp"],
+      "properties": {
+        "target": { "enum": ["editor", "runtime"] },
+        "sessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+        "editorSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+        "runtimeSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+        "processId": { "type": "integer", "minimum": 1 },
+        "processStartedAt": { "type": "string", "format": "date-time" },
+        "publishedAt": { "type": "string", "format": "date-time" },
+        "publicationSequence": { "type": "integer", "minimum": 1 },
+        "lifecycle": { "enum": ["ready", "transitioning", "blocked", "domain-reloading", "compiling", "importing", "building", "playmode-changing"] },
+        "lastUnitySnapshot": { "$ref": "#/$defs/snapshot" },
+        "listener": { "$ref": "#/$defs/listener" },
+        "progress": { "type": "array", "items": { "$ref": "#/$defs/progress" } },
+        "blockers": { "type": "array", "items": { "type": "object" } },
+        "unityVersion": { "type": "string" },
+        "buildStamp": { "type": "string", "minLength": 1 },
+        "toolCatalogFingerprint": { "type": "string" },
+        "executablePath": { "type": "string", "minLength": 1 },
+        "buildId": { "type": "string", "pattern": "^[0-9a-fA-F]{32}$" }
+      },
+      "oneOf": [
+        {
+          "properties": { "target": { "const": "editor" } },
+          "required": ["editorSessionId"],
+          "not": { "required": ["runtimeSessionId"] }
+        },
+        {
+          "properties": { "target": { "const": "runtime" } },
+          "required": ["runtimeSessionId", "executablePath", "buildId"],
+          "not": { "required": ["editorSessionId"] }
+        }
+      ]
+    },
+    "snapshot": {
+      "oneOf": [
+        { "$ref": "#/$defs/editorSnapshot" },
+        { "$ref": "#/$defs/runtimeSnapshot" }
+      ]
+    },
+    "editorSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "observedAt", "sourceEditorSessionId", "sourceListenerGeneration", "fields"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "sourceEditorSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+        "sourceListenerGeneration": { "type": "integer", "minimum": 1 },
+        "fields": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["compile", "import", "build", "playMode", "prefabStage", "activeScene", "runtime"],
+          "properties": {
+            "compile": { "$ref": "#/$defs/knownField" },
+            "import": { "$ref": "#/$defs/knownField" },
+            "build": { "$ref": "#/$defs/knownField" },
+            "playMode": { "$ref": "#/$defs/knownField" },
+            "prefabStage": { "$ref": "#/$defs/knownField" },
+            "activeScene": { "$ref": "#/$defs/knownField" },
+            "runtime": { "$ref": "#/$defs/knownField" }
+          }
+        }
+      }
+    },
+    "runtimeSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "observedAt", "sourceRuntimeSessionId", "sourceListenerGeneration", "fields"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "sourceRuntimeSessionId": { "type": "string", "pattern": "^session-[0-9a-f]{64}$" },
+        "sourceListenerGeneration": { "type": "integer", "minimum": 1 },
+        "fields": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 16,
+          "additionalProperties": { "$ref": "#/$defs/knownField" }
+        }
+      }
+    },
+    "knownField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["known"],
+      "properties": {
+        "known": { "type": "boolean" },
+        "value": true
+      }
+    },
+    "listener": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["listenerId", "generation", "startedAt", "endpoint"],
+      "properties": {
+        "listenerId": { "type": "string", "pattern": "^listener-[0-9a-f]{32}$" },
+        "generation": { "type": "integer", "minimum": 1 },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "endpoint": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["host", "preferredPort", "actualPort", "fallback", "url"],
+          "properties": {
+            "host": { "const": "127.0.0.1" },
+            "preferredPort": { "type": "integer", "minimum": 1024, "maximum": 65535 },
+            "actualPort": { "type": "integer", "minimum": 1024, "maximum": 65535 },
+            "fallback": { "type": "boolean" },
+            "url": { "type": "string", "pattern": "^http://127\\.0\\.0\\.1:[0-9]+$" }
+          }
+        }
+      }
+    },
+    "progress": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/contracts/stable-session/removal-map.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "baselineCommit": "6ff277f361f74e7d85c749557671824d5a46813c",
+  "entries": [
+    { "legacy": "TargetConfig.activeTarget", "finalDisposition": "delete", "verification": "product residual count is zero" },
+    { "legacy": "target current|set|clear", "finalDisposition": "delete public commands", "verification": "top-level help and CLI routing reject them" },
+    { "legacy": "--target instance selector", "finalDisposition": "delete", "verification": "unknown flag is rejected" },
+    { "legacy": "--bridge-endpoint", "finalDisposition": "delete", "verification": "unknown flag is rejected" },
+    { "legacy": "UNITY_CLI_BRIDGE_ENDPOINT", "finalDisposition": "delete", "verification": "product residual count is zero" },
+    { "legacy": "single-ready and active-target fallback", "finalDisposition": "delete", "verification": "non-project CWD returns E_INSTANCE_REQUIRED" },
+    { "legacy": "PID-based instance identity", "finalDisposition": "replace with CanonicalPath v1 SHA-256 identity", "verification": "restart keeps instanceId and health identity matches" },
+    { "legacy": "aggregate instances.json", "finalDisposition": "delete reader and writer", "verification": "registry v3 uses one identity file only" },
+    { "legacy": "Registry/Health v2 heartbeat timestamps", "finalDisposition": "replace with Registry/Health v3 publication plus in-memory main-thread pulse", "verification": "v2 schemas and product fields are absent" },
+    { "legacy": "healthy|stale|unreachable public states", "finalDisposition": "replace with ready|transitioning|blocked|unresponsive|unverifiable|offline|conflict", "verification": "public schema enum equality" },
+    { "legacy": "Bridge mutation withRetry blind replay", "finalDisposition": "delete request-level replay and dedup semantics", "verification": "timeout and disconnect return E_EXECUTION_TIMEOUT; callers decide whether to retry" },
+    { "legacy": "HTTP disconnect cancellation after acceptance", "finalDisposition": "replace with result recovery", "verification": "accepted mutation completes exactly once" },
+    { "legacy": "public editor.state Tool", "finalDisposition": "delete", "verification": "one TS hybrid Context owner remains" },
+    { "legacy": "C# public editor.state Context", "finalDisposition": "replace with private internal.editor.state.snapshot", "verification": "internal command is not discoverable" },
+    { "legacy": "editor.state transition wait", "finalDisposition": "replace with observeNow 4000ms total and 3500ms private Bridge budgets", "verification": "zero wait and no request-level persistence" },
+    { "legacy": "detector BM_CLICK and unscoped Unity process scan", "finalDisposition": "delete from detector", "verification": "read-only selected-PID source audit" },
+    { "legacy": "editor.compile-diagnostics", "finalDisposition": "delete", "verification": "product residual count is zero" },
+    { "legacy": "C# public EditorCompileTool", "finalDisposition": "replace with private persisted coordinator", "verification": "one TS hybrid editor.compile owner remains" },
+    { "legacy": "editor.compile.waitReady", "finalDisposition": "delete", "verification": "waiting is unconditional and field is rejected" },
+    { "legacy": "requested|skippedReason compile success", "finalDisposition": "replace with attributed terminal compile result", "verification": "success requires zero compiler errors and ready state" },
+    { "legacy": "Console text as owned compile diagnostics", "finalDisposition": "replace with CompilationPipeline broker", "verification": "cycle-attributed assembly diagnostics" }
+  ]
+}