@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Infrastructure/UnityCliCompletionProbe.cs

@@ -0,0 +1,515 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private static readonly object CompletionProbeLock = new object();
+        private static readonly Dictionary<string, string> CompletionProbeResourceOwners = new Dictionary<string, string>(StringComparer.Ordinal);
+        private static string CompletionProbeSessionOwner;
+
+        /// <summary>completion proof 的私有读取入口；不会进入公开 Tool registry 或 descriptor。</summary>
+        private sealed class CompletionProofObserverDefinition
+        {
+            public string ReadTool { get; set; }
+            public Type RequestType { get; set; }
+            public Func<object, UnityCliProjectToolContext, CancellationToken, ValueTask<object>> ReadAsync { get; set; }
+            public Func<object, UnityCliProofResourceClaim> ResolveProofResource { get; set; }
+        }
+
+        private static readonly Dictionary<string, CompletionProofObserverDefinition> CompletionProofObservers = CreateCompletionProofObservers();
+
+        /// <summary>只登记完成证明当前支持的 canonical 读取 Tool，禁止项目或 Extension 动态注入。</summary>
+        private static Dictionary<string, CompletionProofObserverDefinition> CreateCompletionProofObservers()
+        {
+            var observers = new Dictionary<string, CompletionProofObserverDefinition>(StringComparer.Ordinal);
+            var gameObject = new SceneGameObjectTool();
+            var component = new SceneGameObjectComponentTool();
+            RegisterCompletionProofObserver(observers, CreateCompletionProofObserver<SceneGameObjectTool.Request, SceneGameObjectTool.Result>(
+                "scene.gameobject", gameObject.ExecuteAsync, gameObject.ResolveProofResource));
+            RegisterCompletionProofObserver(observers, CreateCompletionProofObserver<SceneGameObjectComponentTool.Request, SceneGameObjectComponentTool.Result>(
+                "scene.gameobject.component", component.ExecuteAsync, component.ResolveProofResource));
+            return observers;
+        }
+
+        private static CompletionProofObserverDefinition CreateCompletionProofObserver<TReq, TRes>(
+            string readTool,
+            Func<TReq, UnityCliProjectToolContext, CancellationToken, ValueTask<TRes>> readAsync,
+            Func<TReq, UnityCliProofResourceClaim> resolveProofResource)
+        {
+            return new CompletionProofObserverDefinition
+            {
+                ReadTool = readTool,
+                RequestType = typeof(TReq),
+                ReadAsync = async (input, context, cancellationToken) => (object)await readAsync((TReq)input, context, cancellationToken),
+                ResolveProofResource = input => resolveProofResource((TReq)input)
+            };
+        }
+
+        private static void RegisterCompletionProofObserver(
+            IDictionary<string, CompletionProofObserverDefinition> observers,
+            CompletionProofObserverDefinition observer)
+        {
+            if (observer == null || string.IsNullOrWhiteSpace(observer.ReadTool) || observer.RequestType == null
+                || observer.ReadAsync == null || observer.ResolveProofResource == null)
+                throw new InvalidOperationException("Completion proof observer registration is incomplete.");
+            if (observers.ContainsKey(observer.ReadTool))
+                throw new InvalidOperationException("Duplicate completion proof observer: " + observer.ReadTool);
+            observers.Add(observer.ReadTool, observer);
+        }
+
+        private sealed class CompletionProbePrepared
+        {
+            public CompletionProofObserverDefinition Observer { get; set; }
+            public object Input { get; set; }
+            public UnityCliProofResourceClaim Resource { get; set; }
+            public string SessionId { get; set; }
+            public long ListenerGeneration { get; set; }
+            public string BeforeHash { get; set; }
+            public Dictionary<string, CompletionProbePointerValue> BeforeValues { get; set; }
+        }
+
+        private sealed class CompletionProbePointerValue
+        {
+            public bool Exists { get; set; }
+            public object Value { get; set; }
+        }
+
+        /// <summary>
+        /// 在同一主线程调用内执行 pre-read、唯一 effect barrier 与 fresh post-read。
+        /// 内部 observer、输入 schema、断言、资源 identity、session identity 与互斥 lease 都必须在 effect 前成立。
+        /// </summary>
+        public static UnityCliCompletionProbeReadback ExecuteCompletionProbe(
+            UnityCliProjectToolContext ctx,
+            UnityCliCompletionProbe probe,
+            Action effect)
+        {
+            if (ctx == null) throw new ArgumentNullException("ctx");
+            if (effect == null) throw new ArgumentNullException("effect");
+            var prepared = PrepareCompletionProbe(ctx, probe);
+            AcquireCompletionProbeLease(ctx.RequestId, prepared.Resource.ResourceKey);
+            try
+            {
+                var beforeSnapshot = ReadCompletionProbeSnapshot(ctx, prepared.Observer, prepared.Input, "before");
+                prepared.BeforeHash = CanonicalCompletionProbeHash(beforeSnapshot);
+                prepared.BeforeValues = ResolveCompletionProbePointers(beforeSnapshot, probe.Assertions);
+                ValidateCompletionProbeBefore(probe.Assertions, prepared.BeforeValues);
+
+                ctx.CommitEffect();
+                try
+                {
+                    effect();
+                }
+                catch (Exception exception)
+                {
+                    throw CompletionProbeOutcomeUnknown("effect", exception);
+                }
+
+                EnsureCompletionProbeSessionContinuity(prepared, "post-effect");
+                UnityCliProofResourceClaim afterResource;
+                try
+                {
+                    afterResource = ResolveCompletionProbeResource(prepared.Observer, prepared.Input);
+                }
+                catch (Exception exception)
+                {
+                    throw CompletionProbeOutcomeUnknown("resource-identity", exception);
+                }
+                if (!SameCompletionProbeResource(prepared.Resource, afterResource))
+                    throw CompletionProbeOutcomeUnknown("resource-identity", null);
+
+                object afterSnapshot;
+                try
+                {
+                    afterSnapshot = ReadCompletionProbeSnapshot(ctx, prepared.Observer, prepared.Input, "after");
+                }
+                catch (Exception exception)
+                {
+                    throw CompletionProbeOutcomeUnknown("after-read", exception);
+                }
+                EnsureCompletionProbeSessionContinuity(prepared, "after-read");
+
+                Dictionary<string, CompletionProbePointerValue> afterValues;
+                try
+                {
+                    var afterHash = CanonicalCompletionProbeHash(afterSnapshot);
+                    if (string.Equals(prepared.BeforeHash, afterHash, StringComparison.Ordinal))
+                        throw CompletionProbeOutcomeUnknown("unchanged-canonical-readback", null);
+                    afterValues = ResolveCompletionProbePointers(afterSnapshot, probe.Assertions);
+                    ValidateCompletionProbeAfter(probe.Assertions, afterValues);
+                }
+                catch (BridgeCommandException exception)
+                {
+                    throw CompletionProbeOutcomeUnknown("postcondition", exception);
+                }
+                catch (Exception exception)
+                {
+                    throw CompletionProbeOutcomeUnknown("postcondition", exception);
+                }
+
+                return new UnityCliCompletionProbeReadback
+                {
+                    Assertions = probe.Assertions.Select((assertion, index) => new UnityCliCompletionAssertionReadback
+                    {
+                        Path = assertion.Path,
+                        Value = afterValues[index.ToString(CultureInfo.InvariantCulture)].Exists ? afterValues[index.ToString(CultureInfo.InvariantCulture)].Value : null
+                    }).ToList()
+                };
+            }
+            finally
+            {
+                ReleaseCompletionProbeLease(ctx.RequestId, prepared.Resource.ResourceKey);
+            }
+        }
+
+        /// <summary>解析并校验 probe contract；此方法及其调用链不得产生 Unity mutation。</summary>
+        private static CompletionProbePrepared PrepareCompletionProbe(UnityCliProjectToolContext ctx, UnityCliCompletionProbe probe)
+        {
+            if (probe == null)
+                throw new BridgeCommandException("E_COMPLETION_PROBE_REQUIRED", "This Tool requires completionProbe before it can execute.", "Pass a supported read Tool, input, and before/after assertions.");
+            if (probe.Assertions == null || probe.Assertions.Count == 0)
+                throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "completionProbe requires at least one assertion.", "Declare one or more JSON Pointer assertions with before and after values.");
+            if (probe.Assertions.Count > 32)
+                throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "completionProbe accepts at most 32 assertions.", "Reduce the assertion set to the state changed by this request.");
+            if (EditorApplication.isCompiling || EditorApplication.isUpdating || BuildPipeline.isBuildingPlayer || IsPlayModeChanging())
+                throw new BridgeCommandException("E_UNITY_BUSY", "Unity Editor is not stable enough to capture completionProbe pre-state.", "Wait for editor.state to report ready, then submit a new request.");
+
+            CompletionProofObserverDefinition observer;
+            if (!CompletionProofObservers.TryGetValue(probe.ReadTool ?? string.Empty, out observer))
+                throw new BridgeCommandException("E_COMPLETION_PROBE_READ_TOOL_UNSUPPORTED", "Read Tool is not approved for completion proof: " + (probe.ReadTool ?? "<null>") + ".", "Use a readTool listed by the completionProbe schema enum.");
+
+            object typedInput;
+            try
+            {
+                var inputJson = UnityCliSerializer.Serialize(probe.Input);
+                var schemaFailure = ValidateTypedInput(observer.RequestType, inputJson);
+                if (schemaFailure != null) throw SchemaValidationException(schemaFailure);
+                typedInput = UnityCliSerializer.Deserialize(inputJson, observer.RequestType);
+            }
+            catch (Exception exception)
+            {
+                throw new BridgeCommandException("E_COMPLETION_PROBE_INPUT_INVALID", "completionProbe read Tool input is invalid: " + exception.Message, "Validate the input against tools describe " + observer.ReadTool + " before submitting the Tool.");
+            }
+
+            ValidateCompletionProbeAssertionSyntax(probe.Assertions);
+            var resource = ResolveCompletionProbeResource(observer, typedInput);
+            return new CompletionProbePrepared
+            {
+                Observer = observer,
+                Input = typedInput,
+                Resource = resource,
+                SessionId = EditorSessionId(),
+                ListenerGeneration = CurrentListenerGeneration()
+            };
+        }
+
+        /// <summary>只执行内部 observer delegate；异步或跨帧读取不可用于同调用 proof。</summary>
+        private static object ReadCompletionProbeSnapshot(UnityCliProjectToolContext parent, CompletionProofObserverDefinition observer, object input, string stage)
+        {
+            var readContext = new UnityCliProjectToolContext
+            {
+                RequestId = parent.RequestId,
+                ProjectPath = parent.ProjectPath,
+                LogPath = parent.LogPath,
+                CancellationToken = parent.CancellationToken,
+                Wait = null
+            };
+            var pending = observer.ReadAsync(input, readContext, parent.CancellationToken);
+            if (!pending.IsCompleted)
+                throw new BridgeCommandException("E_COMPLETION_PROBE_OBSERVER_ASYNC", "completionProbe observer did not finish synchronously during " + stage + " read.", "Use a synchronous read Tool supported by the completionProbe schema.");
+            var result = pending.GetAwaiter().GetResult();
+            return UnityCliSerializer.Parse(UnityCliSerializer.Serialize(result));
+        }
+
+        private static UnityCliProofResourceClaim ResolveCompletionProbeResource(CompletionProofObserverDefinition observer, object input)
+        {
+            UnityCliProofResourceClaim claim;
+            try { claim = observer.ResolveProofResource(input); }
+            catch (BridgeCommandException) { throw; }
+            catch (Exception exception)
+            {
+                throw new BridgeCommandException("E_COMPLETION_PROBE_RESOURCE_INVALID", "completionProbe could not resolve a canonical resource: " + exception.Message, "Use an exact read Tool target that resolves one stable resource.");
+            }
+            if (claim == null || string.IsNullOrWhiteSpace(claim.ResourceKey) || string.IsNullOrWhiteSpace(claim.Identity))
+                throw new BridgeCommandException("E_COMPLETION_PROBE_RESOURCE_INVALID", "completionProbe observer returned an incomplete canonical resource claim.", "Use an exact read Tool target that resolves one stable resource.");
+            return claim;
+        }
+
+        private static void AcquireCompletionProbeLease(string requestId, string resourceKey)
+        {
+            lock (CompletionProbeLock)
+            {
+                string owner;
+                if (!string.IsNullOrEmpty(CompletionProbeSessionOwner) && !string.Equals(CompletionProbeSessionOwner, requestId, StringComparison.Ordinal))
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_RESOURCE_BUSY", "Another completionProbe mutation owns the Editor session.", "Wait for the current direct Tool call to finish, then submit a new request.", true, 100);
+                if (CompletionProbeResourceOwners.TryGetValue(resourceKey, out owner) && !string.Equals(owner, requestId, StringComparison.Ordinal))
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_RESOURCE_BUSY", "The completionProbe resource is owned by another request.", "Wait for the current direct Tool call to finish, then submit a new request.", true, 100);
+                CompletionProbeSessionOwner = requestId;
+                CompletionProbeResourceOwners[resourceKey] = requestId;
+            }
+        }
+
+        private static void ReleaseCompletionProbeLease(string requestId, string resourceKey)
+        {
+            lock (CompletionProbeLock)
+            {
+                string owner;
+                if (CompletionProbeResourceOwners.TryGetValue(resourceKey, out owner) && string.Equals(owner, requestId, StringComparison.Ordinal))
+                    CompletionProbeResourceOwners.Remove(resourceKey);
+                if (string.Equals(CompletionProbeSessionOwner, requestId, StringComparison.Ordinal)) CompletionProbeSessionOwner = null;
+            }
+        }
+
+        private static void EnsureCompletionProbeSessionContinuity(CompletionProbePrepared prepared, string stage)
+        {
+            if (!string.Equals(prepared.SessionId, EditorSessionId(), StringComparison.Ordinal)
+                || prepared.ListenerGeneration != CurrentListenerGeneration()
+                || EditorApplication.isCompiling || EditorApplication.isUpdating || IsPlayModeChanging())
+                throw CompletionProbeOutcomeUnknown(stage + "-session", null);
+        }
+
+        private static bool SameCompletionProbeResource(UnityCliProofResourceClaim before, UnityCliProofResourceClaim after)
+        {
+            return before != null && after != null
+                && string.Equals(before.ResourceKey, after.ResourceKey, StringComparison.Ordinal)
+                && string.Equals(before.Identity, after.Identity, StringComparison.Ordinal)
+                && before.InstanceId == after.InstanceId
+                && before.SceneHandle == after.SceneHandle;
+        }
+
+        private static void ValidateCompletionProbeAssertionSyntax(IList<UnityCliCompletionAssertion> assertions)
+        {
+            var seen = new HashSet<string>(StringComparer.Ordinal);
+            foreach (var assertion in assertions)
+            {
+                if (assertion == null || string.IsNullOrEmpty(assertion.Path) || assertion.Path[0] != '/')
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "Each completionProbe assertion path must be a non-empty JSON Pointer.", "Use paths such as /transform/position/x.");
+                DecodeCompletionProbePointer(assertion.Path);
+                var key = assertion.Path + "\n" + assertion.Operator;
+                if (!seen.Add(key))
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "completionProbe contains a duplicate path/operator assertion: " + assertion.Path + ".", "Keep one assertion for each path and operator.");
+                if (assertion.Operator == "approx")
+                {
+                    if (!assertion.Tolerance.HasValue || assertion.Tolerance.Value < 0 || double.IsNaN(assertion.Tolerance.Value) || double.IsInfinity(assertion.Tolerance.Value))
+                        throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "approx requires a finite non-negative tolerance.", "Pass tolerance with every approx assertion.");
+                    RequireCompletionProbeNumber(assertion.Before, "before");
+                    RequireCompletionProbeNumber(assertion.After, "after");
+                }
+                else if (assertion.Tolerance.HasValue)
+                {
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "tolerance is only valid for approx assertions.", "Remove tolerance or use operator approx.");
+                }
+                if (assertion.Operator == "exists" && (!(assertion.Before is bool) || !(assertion.After is bool)))
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "exists before/after values must be booleans.", "Pass true or false for exists assertions.");
+                if (assertion.Operator == "lengthEquals")
+                {
+                    RequireCompletionProbeLength(assertion.Before, "before");
+                    RequireCompletionProbeLength(assertion.After, "after");
+                }
+            }
+        }
+
+        private static Dictionary<string, CompletionProbePointerValue> ResolveCompletionProbePointers(object snapshot, IList<UnityCliCompletionAssertion> assertions)
+        {
+            return assertions.Select(assertion => ResolveCompletionProbePointer(snapshot, assertion.Path))
+                .Select((value, index) => new { Index = index, Value = value })
+                .ToDictionary(item => item.Index.ToString(CultureInfo.InvariantCulture), item => item.Value, StringComparer.Ordinal);
+        }
+
+        private static void ValidateCompletionProbeBefore(IList<UnityCliCompletionAssertion> assertions, Dictionary<string, CompletionProbePointerValue> values)
+        {
+            var anyAfterUnsatisfied = false;
+            for (var index = 0; index < assertions.Count; index++)
+            {
+                var assertion = assertions[index];
+                var observed = values[index.ToString(CultureInfo.InvariantCulture)];
+                if (!EvaluateCompletionProbeAssertion(assertion, assertion.Before, observed))
+                    throw new BridgeCommandException("E_COMPLETION_PROBE_PRECONDITION_FAILED", "completionProbe before assertion failed at " + assertion.Path + ".", "Run the declared read Tool again and submit assertions that match the current resource state.");
+                if (!EvaluateCompletionProbeAssertion(assertion, assertion.After, observed)) anyAfterUnsatisfied = true;
+            }
+            if (!anyAfterUnsatisfied)
+                throw new BridgeCommandException("E_COMPLETION_PROBE_ALREADY_SATISFIED", "All completionProbe after assertions already hold before the effect.", "Choose an operation whose declared post-state differs from the current resource state.");
+        }
+
+        private static void ValidateCompletionProbeAfter(IList<UnityCliCompletionAssertion> assertions, Dictionary<string, CompletionProbePointerValue> values)
+        {
+            for (var index = 0; index < assertions.Count; index++)
+            {
+                var assertion = assertions[index];
+                if (!EvaluateCompletionProbeAssertion(assertion, assertion.After, values[index.ToString(CultureInfo.InvariantCulture)]))
+                    throw new InvalidOperationException("completionProbe after assertion failed at " + assertion.Path + ".");
+            }
+        }
+
+        private static bool EvaluateCompletionProbeAssertion(UnityCliCompletionAssertion assertion, object expected, CompletionProbePointerValue observed)
+        {
+            switch (assertion.Operator)
+            {
+                case "exists": return (bool)expected == observed.Exists;
+                case "equals": return observed.Exists && CompletionProbeJsonEquals(observed.Value, expected);
+                case "notEquals": return observed.Exists && !CompletionProbeJsonEquals(observed.Value, expected);
+                case "approx": return observed.Exists && Math.Abs(CompletionProbeNumber(observed.Value) - CompletionProbeNumber(expected)) <= assertion.Tolerance.Value;
+                case "lengthEquals": return observed.Exists && CompletionProbeLength(observed.Value) == CompletionProbeLength(expected);
+                case "contains": return observed.Exists && CompletionProbeContains(observed.Value, expected);
+                default: throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "Unsupported completionProbe operator: " + assertion.Operator + ".", "Use an operator listed by the completionProbe schema enum.");
+            }
+        }
+
+        private static CompletionProbePointerValue ResolveCompletionProbePointer(object root, string pointer)
+        {
+            var current = root;
+            foreach (var segment in DecodeCompletionProbePointer(pointer))
+            {
+                var dictionary = current as IDictionary<string, object>;
+                if (dictionary != null)
+                {
+                    if (!dictionary.TryGetValue(segment, out current)) return new CompletionProbePointerValue();
+                    continue;
+                }
+                var list = current as IList;
+                int index;
+                if (list == null || !int.TryParse(segment, NumberStyles.None, CultureInfo.InvariantCulture, out index) || index < 0 || index >= list.Count)
+                    return new CompletionProbePointerValue();
+                current = list[index];
+            }
+            return new CompletionProbePointerValue { Exists = true, Value = current };
+        }
+
+        private static string[] DecodeCompletionProbePointer(string pointer)
+        {
+            var parts = pointer.Substring(1).Split('/');
+            for (var index = 0; index < parts.Length; index++)
+            {
+                var part = parts[index];
+                for (var cursor = 0; cursor < part.Length; cursor++)
+                {
+                    if (part[cursor] == '~' && (cursor + 1 >= part.Length || (part[cursor + 1] != '0' && part[cursor + 1] != '1')))
+                        throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "completionProbe contains an invalid JSON Pointer escape.", "Escape ~ as ~0 and / as ~1.");
+                }
+                parts[index] = part.Replace("~1", "/").Replace("~0", "~");
+            }
+            return parts;
+        }
+
+        private static bool CompletionProbeJsonEquals(object left, object right)
+        {
+            if (ReferenceEquals(left, right)) return true;
+            if (left == null || right == null) return false;
+            if (IsCompletionProbeNumber(left) && IsCompletionProbeNumber(right)) return CompletionProbeNumber(left) == CompletionProbeNumber(right);
+            var leftDictionary = left as IDictionary<string, object>;
+            var rightDictionary = right as IDictionary<string, object>;
+            if (leftDictionary != null || rightDictionary != null)
+            {
+                if (leftDictionary == null || rightDictionary == null || leftDictionary.Count != rightDictionary.Count) return false;
+                return leftDictionary.All(pair => rightDictionary.ContainsKey(pair.Key) && CompletionProbeJsonEquals(pair.Value, rightDictionary[pair.Key]));
+            }
+            var leftList = left as IList;
+            var rightList = right as IList;
+            if (leftList != null || rightList != null)
+            {
+                if (leftList == null || rightList == null || leftList.Count != rightList.Count) return false;
+                for (var index = 0; index < leftList.Count; index++) if (!CompletionProbeJsonEquals(leftList[index], rightList[index])) return false;
+                return true;
+            }
+            return left.GetType() == right.GetType() && left.Equals(right);
+        }
+
+        private static bool CompletionProbeContains(object actual, object expected)
+        {
+            var text = actual as string;
+            var expectedText = expected as string;
+            if (text != null && expectedText != null) return text.IndexOf(expectedText, StringComparison.Ordinal) >= 0;
+            var list = actual as IList;
+            if (list != null) return list.Cast<object>().Any(item => CompletionProbeJsonEquals(item, expected));
+            var dictionary = actual as IDictionary<string, object>;
+            return dictionary != null && expectedText != null && dictionary.ContainsKey(expectedText);
+        }
+
+        private static bool IsCompletionProbeNumber(object value)
+        {
+            return value is byte || value is sbyte || value is short || value is ushort || value is int || value is uint
+                || value is long || value is ulong || value is float || value is double || value is decimal;
+        }
+
+        private static void RequireCompletionProbeNumber(object value, string field)
+        {
+            if (!IsCompletionProbeNumber(value))
+                throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "approx " + field + " must be a JSON number.", "Pass numeric before/after values without string coercion.");
+            CompletionProbeNumber(value);
+        }
+
+        private static double CompletionProbeNumber(object value)
+        {
+            if (!IsCompletionProbeNumber(value)) throw new InvalidOperationException("Observed value is not numeric.");
+            var number = Convert.ToDouble(value, CultureInfo.InvariantCulture);
+            if (double.IsNaN(number) || double.IsInfinity(number)) throw new InvalidOperationException("Observed number is not finite.");
+            return number;
+        }
+
+        private static void RequireCompletionProbeLength(object value, string field)
+        {
+            if (!IsCompletionProbeNumber(value) || CompletionProbeNumber(value) < 0 || Math.Floor(CompletionProbeNumber(value)) != CompletionProbeNumber(value))
+                throw new BridgeCommandException("E_COMPLETION_PROBE_ASSERTION_INVALID", "lengthEquals " + field + " must be a non-negative integer.", "Pass an integer length as before/after.");
+        }
+
+        private static int CompletionProbeLength(object value)
+        {
+            if (IsCompletionProbeNumber(value)) return checked((int)CompletionProbeNumber(value));
+            var text = value as string;
+            if (text != null) return text.Length;
+            var list = value as IList;
+            if (list != null) return list.Count;
+            var dictionary = value as IDictionary<string, object>;
+            if (dictionary != null) return dictionary.Count;
+            throw new InvalidOperationException("Observed value has no length.");
+        }
+
+        private static string CanonicalCompletionProbeHash(object value)
+        {
+            var canonical = CanonicalCompletionProbeValue(value);
+            using (var sha = SHA256.Create())
+            {
+                var bytes = Encoding.UTF8.GetBytes(UnityCliSerializer.Serialize(canonical));
+                return BitConverter.ToString(sha.ComputeHash(bytes)).Replace("-", string.Empty).ToLowerInvariant();
+            }
+        }
+
+        private static object CanonicalCompletionProbeValue(object value)
+        {
+            var dictionary = value as IDictionary<string, object>;
+            if (dictionary != null)
+            {
+                var sorted = new SortedDictionary<string, object>(StringComparer.Ordinal);
+                foreach (var pair in dictionary) sorted[pair.Key] = CanonicalCompletionProbeValue(pair.Value);
+                return sorted;
+            }
+            var list = value as IList;
+            if (list != null) return list.Cast<object>().Select(CanonicalCompletionProbeValue).ToList();
+            return value;
+        }
+
+        private static BridgeCommandException CompletionProbeOutcomeUnknown(string stage, Exception cause)
+        {
+            return new BridgeCommandException(
+                "E_EXECUTION_TIMEOUT",
+                "The completionProbe result cannot be confirmed. Check the affected business state.",
+                new Dictionary<string, object>
+                {
+                    { "stage", stage },
+                    { "cause", cause == null ? null : cause.Message }
+                },
+                new[] { "Run the declared read Tool and inspect the target resource before submitting another request." });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliEditorStateSnapshot.cs

@@ -0,0 +1,84 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>采集同一时刻的Unity只读状态，供私有命令与Registry publication复用。</summary>
+        private static Dictionary<string, object> SampleEditorStateSnapshot(string observedAt = null)
+        {
+            var scene = SceneManager.GetActiveScene();
+            var prefabStage = PrefabStageUtility.GetCurrentPrefabStage();
+            return new Dictionary<string, object>
+            {
+                { "schemaVersion", 1L },
+                { "observedAt", observedAt ?? DateTime.UtcNow.ToString("O", CultureInfo.InvariantCulture) },
+                { "sourceEditorSessionId", EditorSessionId() },
+                { "sourceListenerGeneration", CurrentListenerGeneration() },
+                { "fields", new Dictionary<string, object>
+                    {
+                        { "compile", KnownSnapshotField(EditorApplication.isCompiling) },
+                        { "import", KnownSnapshotField(EditorApplication.isUpdating) },
+                        { "build", KnownSnapshotField(BuildPipeline.isBuildingPlayer) },
+                        { "playMode", KnownSnapshotField(IsPlayModeChanging() ? "transitioning" : (EditorApplication.isPlaying ? "play" : "edit")) },
+                        { "prefabStage", KnownSnapshotField(prefabStage == null ? null : new Dictionary<string, object> { { "assetPath", prefabStage.assetPath }, { "sceneName", prefabStage.scene.name } }) },
+                        { "activeScene", KnownSnapshotField(scene.IsValid() ? new Dictionary<string, object> { { "name", scene.name }, { "path", scene.path }, { "isDirty", scene.isDirty } } : null) },
+                        { "runtime", KnownSnapshotField(new Dictionary<string, object> { { "ready", EditorApplication.isPlaying && !IsPlayModeChanging() }, { "sessionId", currentPlayModeSessionId ?? string.Empty } }) }
+                    }
+                }
+            };
+        }
+
+        /// <summary>内部快照命令仅供 TS hybrid Context 探测，不能进入公开能力目录。</summary>
+        private static void RegisterEditorStateSnapshotCommand(BridgeCommandRegistry registry)
+        {
+            registry.Register<UnityCli.Protocol.BridgeRequest>(
+                "internal.editor.state.snapshot",
+                "internal",
+                false,
+                30000,
+                (request, cancellationToken) =>
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    return new System.Threading.Tasks.ValueTask<object>(new Dictionary<string, object>
+                    {
+                        { "snapshot", SampleEditorStateSnapshot() },
+                        { "progress", SnapshotProgress() },
+                        { "blockers", new List<object>() }
+                    });
+                });
+        }
+
+        private static bool IsEditorStateSnapshotCommand(string command)
+        {
+            return string.Equals(command, "internal.editor.state.snapshot", StringComparison.Ordinal);
+        }
+
+        private static Dictionary<string, object> KnownSnapshotField(object value)
+        {
+            return new Dictionary<string, object> { { "known", true }, { "value", value } };
+        }
+
+        private static List<object> SnapshotProgress()
+        {
+            var progress = new List<object>();
+            if (domainReloading) progress.Add(SnapshotProgressItem("domain-reload", "Reloading assemblies"));
+            if (EditorApplication.isCompiling) progress.Add(SnapshotProgressItem("script-compile", "Compiling scripts"));
+            if (EditorApplication.isUpdating) progress.Add(SnapshotProgressItem("asset-import", "Importing assets"));
+            if (BuildPipeline.isBuildingPlayer) progress.Add(SnapshotProgressItem("build", "Building player"));
+            return progress;
+        }
+
+        private static Dictionary<string, object> SnapshotProgressItem(string kind, string title)
+        {
+            return new Dictionary<string, object> { { "kind", kind }, { "title", title }, { "value", null }, { "canWait", true }, { "source", "unity" } };
+        }
+    }
+}
+#endif