@alpsckr/unitycli 0.4.3 → 0.4.4

package/unitypkg/Shared/UnityCliRequestBudget.cs

@@ -0,0 +1,352 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading;
+
+namespace UnityCli
+{
+    /// <summary>为数值协议字段声明公开最小值与最大值，并由 schema 与执行前校验共同强制。</summary>
+    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false, Inherited = true)]
+    public sealed class UnityCliRangeAttribute : Attribute
+    {
+        public UnityCliRangeAttribute(long minimum, long maximum) { Minimum = minimum; Maximum = maximum; }
+        public long Minimum { get; private set; }
+        public long Maximum { get; private set; }
+    }
+
+    /// <summary>为集合协议字段声明公开元素数量范围，并由 schema 与执行前校验共同强制。</summary>
+    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false, Inherited = true)]
+    public sealed class UnityCliItemsRangeAttribute : Attribute
+    {
+        public UnityCliItemsRangeAttribute(int minimum, int maximum) { Minimum = minimum; Maximum = maximum; }
+        public int Minimum { get; private set; }
+        public int Maximum { get; private set; }
+    }
+
+    /// <summary>公开读取预算输入；调用方可以收紧预算，但不能超过产品冻结上限。</summary>
+    public sealed class UnityCliReadBudgetInput
+    {
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxScannedRecords)] public long? MaxScannedRecords { get; set; }
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxNodes)] public long? MaxNodes { get; set; }
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxGetters)] public long? MaxGetters { get; set; }
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxReflectionCalls)] public long? MaxReflectionCalls { get; set; }
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxMainThreadMilliseconds)] public long? MaxMainThreadMilliseconds { get; set; }
+        [UnityCliRange(1L, UnityCliRequestBudget.AbsoluteMaxSerializedUtf8Bytes)] public long? MaxSerializedUtf8Bytes { get; set; }
+    }
+
+    /// <summary>请求预算实际消耗；估算输出与最终 envelope 的实际 UTF-8 字节分别报告。</summary>
+    public sealed class UnityCliRequestBudgetUsage
+    {
+        private readonly UnityCliRequestBudget liveBudget;
+        private long scannedRecords;
+        private long nodes;
+        private long getters;
+        private long reflectionCalls;
+        private long mainThreadMilliseconds;
+        private long estimatedSerializedUtf8Bytes;
+        private long actualSerializedUtf8Bytes;
+        private string exhaustedDimension;
+
+        public UnityCliRequestBudgetUsage() { }
+
+        internal UnityCliRequestBudgetUsage(UnityCliRequestBudget liveBudget)
+        {
+            this.liveBudget = liveBudget;
+        }
+
+        public long ScannedRecords { get { return liveBudget == null ? scannedRecords : liveBudget.ScannedRecords; } set { scannedRecords = value; } }
+        public long Nodes { get { return liveBudget == null ? nodes : liveBudget.Nodes; } set { nodes = value; } }
+        public long Getters { get { return liveBudget == null ? getters : liveBudget.Getters; } set { getters = value; } }
+        public long ReflectionCalls { get { return liveBudget == null ? reflectionCalls : liveBudget.ReflectionCalls; } set { reflectionCalls = value; } }
+        public long MainThreadMilliseconds { get { return liveBudget == null ? mainThreadMilliseconds : liveBudget.MainThreadMilliseconds; } set { mainThreadMilliseconds = value; } }
+        public long EstimatedSerializedUtf8Bytes { get { return liveBudget == null ? estimatedSerializedUtf8Bytes : liveBudget.EstimatedSerializedUtf8Bytes; } set { estimatedSerializedUtf8Bytes = value; } }
+        public long ActualSerializedUtf8Bytes { get { return liveBudget == null ? actualSerializedUtf8Bytes : liveBudget.ActualSerializedUtf8Bytes; } set { actualSerializedUtf8Bytes = value; } }
+        public string ExhaustedDimension { get { return liveBudget == null ? exhaustedDimension : liveBudget.ExhaustedDimension; } set { exhaustedDimension = value; } }
+    }
+
+    /// <summary>可注入的单调时钟，生产使用 Stopwatch，测试使用手工时钟。</summary>
+    public interface IUnityCliMonotonicClock
+    {
+        long ElapsedMilliseconds { get; }
+    }
+
+    public sealed class UnityCliStopwatchClock : IUnityCliMonotonicClock
+    {
+        private readonly System.Diagnostics.Stopwatch stopwatch = System.Diagnostics.Stopwatch.StartNew();
+        public long ElapsedMilliseconds { get { return stopwatch.ElapsedMilliseconds; } }
+    }
+
+    /// <summary>遍历预算耗尽；上层将其归约为稳定 E_REQUEST_BUDGET_EXCEEDED。</summary>
+    public sealed class UnityCliRequestBudgetExceededException : Exception
+    {
+        public UnityCliRequestBudgetExceededException(string dimension)
+            : base("Request-wide Unity main-thread budget exhausted: " + dimension + ".")
+        {
+            Dimension = dimension;
+        }
+
+        public string Dimension { get; private set; }
+    }
+
+    /// <summary>
+    /// 一次 Tool 请求共用的预算账本。每次原始读取前先消费对应维度；elapsed 使用单调时钟，
+    /// cancellation 与所有维度共享同一终止点，禁止子路径或递归重新创建预算。
+    /// </summary>
+    public sealed class UnityCliRequestBudget
+    {
+        public const long DefaultMaxScannedRecords = 10000L;
+        public const long AbsoluteMaxScannedRecords = 100000L;
+        public const long DefaultMaxNodes = 4096L;
+        public const long AbsoluteMaxNodes = 20000L;
+        public const long DefaultMaxGetters = 2048L;
+        public const long AbsoluteMaxGetters = 10000L;
+        public const long DefaultMaxReflectionCalls = 4096L;
+        public const long AbsoluteMaxReflectionCalls = 20000L;
+        public const long DefaultMaxMainThreadMilliseconds = 250L;
+        public const long AbsoluteMaxMainThreadMilliseconds = 2000L;
+        public const long DefaultMaxSerializedUtf8Bytes = 1024L * 1024L;
+        public const long AbsoluteMaxSerializedUtf8Bytes = 8L * 1024L * 1024L;
+
+        private readonly IUnityCliMonotonicClock clock;
+        private readonly CancellationToken cancellationToken;
+        private readonly long maxScannedRecords;
+        private readonly long maxNodes;
+        private readonly long maxGetters;
+        private readonly long maxReflectionCalls;
+        private readonly long maxMainThreadMilliseconds;
+        private readonly long maxSerializedUtf8Bytes;
+        private long scannedRecords;
+        private long nodes;
+        private long getters;
+        private long reflectionCalls;
+        private long serializedUtf8Bytes;
+        private long mainThreadMilliseconds;
+        private long lastClockMilliseconds;
+        private string exhaustedDimension;
+
+        public UnityCliRequestBudget(UnityCliReadBudgetInput input, long executionTimeoutMilliseconds, CancellationToken cancellationToken, IUnityCliMonotonicClock clock = null)
+        {
+            input = input ?? new UnityCliReadBudgetInput();
+            maxScannedRecords = Limit(input.MaxScannedRecords, DefaultMaxScannedRecords, AbsoluteMaxScannedRecords, "maxScannedRecords");
+            maxNodes = Limit(input.MaxNodes, DefaultMaxNodes, AbsoluteMaxNodes, "maxNodes");
+            maxGetters = Limit(input.MaxGetters, DefaultMaxGetters, AbsoluteMaxGetters, "maxGetters");
+            maxReflectionCalls = Limit(input.MaxReflectionCalls, DefaultMaxReflectionCalls, AbsoluteMaxReflectionCalls, "maxReflectionCalls");
+            var requestedElapsed = Limit(input.MaxMainThreadMilliseconds, DefaultMaxMainThreadMilliseconds, AbsoluteMaxMainThreadMilliseconds, "maxMainThreadMilliseconds");
+            maxMainThreadMilliseconds = executionTimeoutMilliseconds > 0L ? Math.Min(requestedElapsed, executionTimeoutMilliseconds) : requestedElapsed;
+            maxSerializedUtf8Bytes = Limit(input.MaxSerializedUtf8Bytes, DefaultMaxSerializedUtf8Bytes, AbsoluteMaxSerializedUtf8Bytes, "maxSerializedUtf8Bytes");
+            this.cancellationToken = cancellationToken;
+            this.clock = clock ?? new UnityCliStopwatchClock();
+            lastClockMilliseconds = this.clock.ElapsedMilliseconds;
+        }
+
+        private long actualSerializedUtf8Bytes;
+
+        public long MaxSerializedUtf8Bytes { get { return maxSerializedUtf8Bytes; } }
+        public long RemainingScannedRecords { get { return Math.Max(0L, maxScannedRecords - scannedRecords); } }
+        public long RemainingNodes { get { return Math.Max(0L, maxNodes - nodes); } }
+        public long RemainingGetters { get { return Math.Max(0L, maxGetters - getters); } }
+        public long RemainingReflectionCalls { get { return Math.Max(0L, maxReflectionCalls - reflectionCalls); } }
+        public bool IsExhausted { get { return exhaustedDimension != null; } }
+        public string ExhaustedDimension { get { return exhaustedDimension; } }
+        internal long ScannedRecords { get { return scannedRecords; } }
+        internal long Nodes { get { return nodes; } }
+        internal long Getters { get { return getters; } }
+        internal long ReflectionCalls { get { return reflectionCalls; } }
+        internal long MainThreadMilliseconds { get { return Math.Max(0L, mainThreadMilliseconds); } }
+        internal long EstimatedSerializedUtf8Bytes { get { return serializedUtf8Bytes; } }
+        internal long ActualSerializedUtf8Bytes { get { return actualSerializedUtf8Bytes; } }
+
+        public bool TryConsumeScannedRecord() { return TryConsume(ref scannedRecords, maxScannedRecords, "scannedRecords"); }
+        public bool TryConsumeNode() { return TryConsume(ref nodes, maxNodes, "nodes"); }
+        public bool TryConsumeGetter() { return TryConsume(ref getters, maxGetters, "getters"); }
+        public bool TryConsumeReflectionCall() { return TryConsume(ref reflectionCalls, maxReflectionCalls, "reflectionCalls"); }
+
+        /// <summary>在批量 API 调用前一次性保留可验证 cardinality，避免先物化后超限。</summary>
+        public bool TryConsumeScannedRecords(long count) { return TryConsumeMany(ref scannedRecords, maxScannedRecords, count, "scannedRecords"); }
+        public bool TryConsumeNodes(long count) { return TryConsumeMany(ref nodes, maxNodes, count, "nodes"); }
+        public bool TryConsumeGetters(long count) { return TryConsumeMany(ref getters, maxGetters, count, "getters"); }
+        public bool TryConsumeReflectionCalls(long count) { return TryConsumeMany(ref reflectionCalls, maxReflectionCalls, count, "reflectionCalls"); }
+
+        /// <summary>在原始读取前检查取消与单调 elapsed；false 表示调用方必须返回 continuation。</summary>
+        public bool TryCheckpoint()
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            var now = clock.ElapsedMilliseconds;
+            if (now > lastClockMilliseconds) mainThreadMilliseconds += now - lastClockMilliseconds;
+            lastClockMilliseconds = now;
+            if (mainThreadMilliseconds < maxMainThreadMilliseconds) return exhaustedDimension == null;
+            Exhaust("mainThreadMilliseconds");
+            return false;
+        }
+
+        /// <summary>异步框架 wait 返回后重置采样基线；等待时间不属于 Unity 主线程工作。</summary>
+        public void ResumeAfterWait()
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            lastClockMilliseconds = clock.ElapsedMilliseconds;
+        }
+
+        public void CheckpointOrThrow()
+        {
+            if (!TryCheckpoint()) throw new UnityCliRequestBudgetExceededException(exhaustedDimension);
+        }
+
+        /// <summary>构造动态输出时预留确定的 UTF-8 文本字节；最终 JSON 仍由框架做精确检查。</summary>
+        public bool TryReserveSerializedUtf8(string value)
+        {
+            return TryReserveSerializedUtf8Bytes(value == null ? 4L : Encoding.UTF8.GetByteCount(value));
+        }
+
+        /// <summary>为 JSON 结构或已知编码结果预留确定字节，避免先分配完整字符串。</summary>
+        public bool TryReserveSerializedUtf8Bytes(long bytes)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (!TryCheckpoint()) return false;
+            if (bytes < 0L || bytes > maxSerializedUtf8Bytes - serializedUtf8Bytes)
+            {
+                Exhaust("serializedUtf8Bytes");
+                return false;
+            }
+            serializedUtf8Bytes += bytes;
+            return true;
+        }
+
+        /// <summary>序列化器增量检查最终 JSON 的实际 UTF-8 长度，不覆盖 Tool 侧估算。</summary>
+        public void ValidateSerializedUtf8Bytes(long bytes)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (bytes < 0L || bytes > maxSerializedUtf8Bytes)
+            {
+                Exhaust("serializedUtf8Bytes");
+                throw new UnityCliRequestBudgetExceededException("serializedUtf8Bytes");
+            }
+        }
+
+        /// <summary>记录最终成功 envelope 的实际 UTF-8 长度；调用方负责在返回前使自描述长度收敛。</summary>
+        internal void ObserveActualSerializedUtf8Bytes(long bytes)
+        {
+            ValidateSerializedUtf8Bytes(bytes);
+            actualSerializedUtf8Bytes = bytes;
+        }
+
+        public UnityCliRequestBudgetUsage Usage()
+        {
+            return new UnityCliRequestBudgetUsage(this);
+        }
+
+        private bool TryConsume(ref long current, long maximum, string dimension)
+        {
+            return TryConsumeMany(ref current, maximum, 1L, dimension);
+        }
+
+        private bool TryConsumeMany(ref long current, long maximum, long count, string dimension)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            if (!TryCheckpoint()) return false;
+            if (count < 0L || count > maximum - current)
+            {
+                Exhaust(dimension);
+                return false;
+            }
+            current += count;
+            return true;
+        }
+
+        private void Exhaust(string dimension)
+        {
+            if (exhaustedDimension == null) exhaustedDimension = dimension;
+        }
+
+        private static long Limit(long? requested, long fallback, long maximum, string field)
+        {
+            var value = requested ?? fallback;
+            if (value < 1L || value > maximum)
+                throw new ArgumentOutOfRangeException(field, value, field + " must be between 1 and " + maximum.ToString(CultureInfo.InvariantCulture) + ".");
+            return value;
+        }
+    }
+
+    /// <summary>输入按 newest-first 排序，返回同时满足 count/bytes 的稳定保留索引。</summary>
+    public static class UnityCliRetentionPlanner
+    {
+        public static HashSet<int> RetainedIndices(IReadOnlyList<long> sizes, int maximumCount, long maximumBytes)
+        {
+            if (sizes == null) throw new ArgumentNullException("sizes");
+            if (maximumCount < 1) throw new ArgumentOutOfRangeException("maximumCount");
+            if (maximumBytes < 1L) throw new ArgumentOutOfRangeException("maximumBytes");
+            var result = new HashSet<int>();
+            long bytes = 0L;
+            for (var index = 0; index < sizes.Count && result.Count < maximumCount; index++)
+            {
+                var size = sizes[index];
+                if (size < 0L) throw new ArgumentOutOfRangeException("sizes");
+                if (size > maximumBytes - bytes) break;
+                bytes += size;
+                result.Add(index);
+            }
+            return result;
+        }
+    }
+
+    /// <summary>稳定 continuation 的无状态编码；generation/scope 不匹配时调用方必须拒绝。</summary>
+    public static class UnityCliContinuationToken
+    {
+        public static string Create(string scope, string generation, string position)
+        {
+            return "ucli1." + Encode(scope) + "." + Encode(generation) + "." + Encode(position ?? string.Empty);
+        }
+
+        public static bool TryParse(string token, string expectedScope, string expectedGeneration, out string position)
+        {
+            position = null;
+            if (string.IsNullOrEmpty(token) || token.Length > 4096) return false;
+            var parts = token.Split('.');
+            if (parts.Length != 4 || parts[0] != "ucli1") return false;
+            string scope;
+            string generation;
+            try
+            {
+                scope = Decode(parts[1]);
+                generation = Decode(parts[2]);
+                position = Decode(parts[3]);
+            }
+            catch
+            {
+                position = null;
+                return false;
+            }
+            return string.Equals(scope, expectedScope, StringComparison.Ordinal)
+                && string.Equals(generation, expectedGeneration, StringComparison.Ordinal);
+        }
+
+        public static string Fingerprint(string value)
+        {
+            using (var sha = SHA256.Create())
+            {
+                var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(value ?? string.Empty));
+                var builder = new StringBuilder(bytes.Length * 2);
+                foreach (var item in bytes) builder.Append(item.ToString("x2", CultureInfo.InvariantCulture));
+                return builder.ToString();
+            }
+        }
+
+        private static string Encode(string value)
+        {
+            return Convert.ToBase64String(Encoding.UTF8.GetBytes(value ?? string.Empty)).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+        }
+
+        private static string Decode(string value)
+        {
+            var padded = value.Replace('-', '+').Replace('_', '/');
+            switch (padded.Length % 4)
+            {
+                case 2: padded += "=="; break;
+                case 3: padded += "="; break;
+                case 1: throw new FormatException("Invalid base64url continuation component.");
+            }
+            return Encoding.UTF8.GetString(Convert.FromBase64String(padded));
+        }
+    }
+}

package/unitypkg/Shared/UnityCliRuntimeRequestPublication.cs

@@ -0,0 +1,107 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace UnityCli
+{
+    /// <summary>Runtime request cache的纯事务reservation；只在enqueue成功后提交淘汰。</summary>
+    public sealed class UnityCliRuntimeRequestPublication<T>
+    {
+        public sealed class Reservation
+        {
+            internal Reservation(string requestId, string requestDigest, string evictionRequestId, T evictionCandidate)
+            {
+                RequestId = requestId;
+                RequestDigest = requestDigest;
+                EvictionRequestId = evictionRequestId;
+                EvictionCandidate = evictionCandidate;
+            }
+            public string RequestId { get; private set; }
+            public string RequestDigest { get; private set; }
+            public string EvictionRequestId { get; private set; }
+            internal T EvictionCandidate { get; private set; }
+            public bool HasEviction { get { return EvictionRequestId != null; } }
+        }
+
+        private readonly int capacity;
+        private readonly Dictionary<string, T> entries = new Dictionary<string, T>(StringComparer.Ordinal);
+        private readonly Dictionary<string, string> digests = new Dictionary<string, string>(StringComparer.Ordinal);
+
+        public UnityCliRuntimeRequestPublication(int capacity)
+        {
+            if (capacity < 1) throw new ArgumentOutOfRangeException("capacity");
+            this.capacity = capacity;
+        }
+
+        public int Count { get { return entries.Count; } }
+        public IEnumerable<T> Values { get { return entries.Values.ToArray(); } }
+
+        public bool TryGet(string requestId, out T value)
+        {
+            return entries.TryGetValue(requestId, out value);
+        }
+
+        public bool IsIdentityMatch(string requestId, string requestDigest)
+        {
+            string digest;
+            return digests.TryGetValue(requestId, out digest) && string.Equals(digest, requestDigest, StringComparison.Ordinal);
+        }
+
+        /// <summary>规划只读且可重复；无可淘汰terminal时不修改当前cache。</summary>
+        public Reservation Plan(string requestId, string requestDigest, Func<T, bool> isCompleted, Func<T, long> order)
+        {
+            if (string.IsNullOrWhiteSpace(requestId)) throw new ArgumentException("requestId is required.", "requestId");
+            if (string.IsNullOrWhiteSpace(requestDigest)) throw new ArgumentException("requestDigest is required.", "requestDigest");
+            if (isCompleted == null) throw new ArgumentNullException("isCompleted");
+            if (order == null) throw new ArgumentNullException("order");
+            T existing;
+            if (entries.TryGetValue(requestId, out existing))
+            {
+                if (!IsIdentityMatch(requestId, requestDigest)) throw new InvalidOperationException("Request identity does not match the existing cache entry.");
+                return new Reservation(requestId, requestDigest, null, existing);
+            }
+            if (entries.Count < capacity) return new Reservation(requestId, requestDigest, null, default(T));
+            var completed = entries.Where(pair => isCompleted(pair.Value)).OrderBy(pair => order(pair.Value)).ToArray();
+            return completed.Length == 0 ? null : new Reservation(requestId, requestDigest, completed[0].Key, completed[0].Value);
+        }
+
+        /// <summary>先加入新entry并提交enqueue；enqueue失败时旧entry保持不变，新entry回滚。</summary>
+        public bool Publish(Reservation reservation, T value, Func<T, bool> enqueue)
+        {
+            if (reservation == null) throw new ArgumentNullException("reservation");
+            if (enqueue == null) throw new ArgumentNullException("enqueue");
+            if (entries.ContainsKey(reservation.RequestId)) return IsIdentityMatch(reservation.RequestId, reservation.RequestDigest);
+            if (entries.Count >= capacity && !reservation.HasEviction) return false;
+            if (reservation.HasEviction)
+            {
+                T current;
+                if (!entries.TryGetValue(reservation.EvictionRequestId, out current) || !object.ReferenceEquals(current, reservation.EvictionCandidate)) return false;
+            }
+            entries.Add(reservation.RequestId, value);
+            digests.Add(reservation.RequestId, reservation.RequestDigest);
+            try
+            {
+                if (!enqueue(value))
+                {
+                    entries.Remove(reservation.RequestId);
+                    digests.Remove(reservation.RequestId);
+                    return false;
+                }
+                if (reservation.HasEviction)
+                {
+                    entries.Remove(reservation.EvictionRequestId);
+                    digests.Remove(reservation.EvictionRequestId);
+                }
+                return true;
+            }
+            catch
+            {
+                entries.Remove(reservation.RequestId);
+                digests.Remove(reservation.RequestId);
+                throw;
+            }
+        }
+
+        public void Clear() { entries.Clear(); digests.Clear(); }
+    }
+}

package/unitypkg/Tests/Editor/UnityCli.Editor.Tests.asmdef

@@ -1,7 +1,7 @@
 {
   "name": "UnityCli.Editor.Tests",
   "rootNamespace": "UnityCli.Tests",
-  "references": ["UnityCli.Shared"],
+  "references": ["UnityCli.Shared", "UnityCli.Editor", "UnityCli.Runtime"],
   "includePlatforms": ["Editor"],
   "excludePlatforms": [],
   "allowUnsafeCode": false,
@@ -10,6 +10,6 @@
   "autoReferenced": false,
   "defineConstraints": [],
   "versionDefines": [],
-  "noEngineReferences": true,
+  "noEngineReferences": false,
   "optionalUnityReferences": ["TestAssemblies"]
 }