@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Infrastructure/UnityCliPackageEmbedCoordinator.cs

@@ -0,0 +1,147 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Reflection;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEngine;
+using UnityCli.Protocol;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>package.embed 的跨 domain reload Package Manager 协调器。</summary>
+        internal static class UnityCliPackageEmbedCoordinator
+        {
+            private static readonly Coordinator Instance = new Coordinator();
+            private static readonly Dictionary<string, object> ActiveRequests = new Dictionary<string, object>(StringComparer.Ordinal);
+            internal static bool IsCommand(string command) { return Instance.IsCommand(command); }
+            internal static void Register(BridgeCommandRegistry registry) { Instance.Register(registry); }
+            internal static Task<string> Execute(BridgeRequest request, byte[] raw, Func<bool> accept, CancellationToken ct) { return Instance.Execute(request, raw, accept, ct); }
+            internal static void Initialize() { ActiveRequests.Clear(); }
+            internal static void Shutdown() { ActiveRequests.Clear(); }
+            internal static void BeforeReload() { ActiveRequests.Clear(); Instance.Update(root => root["reloadObserved"] = true); }
+            internal static void Tick() { Instance.Tick(); }
+
+            private sealed class Coordinator : UnityCliReloadOperation
+            {
+                protected override string Scope { get { return "package-embed"; } }
+                protected override string StartCommand { get { return "internal.package.embed.start"; } }
+                protected override string StatusCommand { get { return "internal.package.embed.status"; } }
+                protected override string OperationDisplayName { get { return "Package embed"; } }
+                protected override int CommandTimeoutMs { get { return 120000; } }
+                protected override object DeserializeStartArgs(BridgeRequest request) { return request.DeserializeArgs<Args>(); }
+                protected override void ValidateStart(object value)
+                {
+                    var args = (Args)value;
+                    if (args == null || string.IsNullOrEmpty(args.Package)) throw new BridgeCommandException("E_PACKAGE_ID_REQUIRED", "package.embed requires --package <id>.", "Pass a package id like com.unity.x.");
+                    if (EditorApplication.isPlaying || IsPlayModeChanging()) throw new BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "package.embed is editor-only and requires stable Edit Mode.");
+                }
+                protected override void ValidateLoadedRoot(Dictionary<string, object> root)
+                {
+                    ValidateRootContract(root, new[] { "package", "reloadObserved", "rootContractDigest" }, "queued", "embed_started", "waiting_completed", "waiting_stable");
+                    var packageId = Text(root, "package");
+                    if (string.IsNullOrWhiteSpace(packageId) || packageId.Length > 200 || packageId.IndexOf('/') >= 0 || packageId.IndexOf('\\') >= 0)
+                        throw new InvalidDataException("Package embed active root fields are invalid.");
+                    if (!string.Equals(Text(root, "rootContractDigest"), PackageEmbedRootContractDigest(root), StringComparison.Ordinal))
+                        throw new InvalidDataException("Package embed immutable root contract changed.");
+                    var fenced = HasExactEffectFence("package-embed", root, "package-embed");
+                    if ((Text(root, "phase") == "queued") == fenced)
+                        throw new InvalidDataException("Package embed effect fence is inconsistent with phase.");
+                }
+
+                private static string PackageEmbedRootContractDigest(Dictionary<string, object> root)
+                {
+                    return UnityCliSerializer.Sha256Canonical(new Dictionary<string, object> { { "package", root["package"] } });
+                }
+
+                protected override object Planned(object value)
+                {
+                    var args = (Args)value;
+                    return new Result { PackageId = args.Package, EmbeddedPath = "Packages/" + args.Package, PlannedEffects = Effects(args.Package) };
+                }
+                protected override Dictionary<string, object> CreateRoot(BridgeRequest request, string digest, object value)
+                {
+                    var args = (Args)value;
+                    var root = new Dictionary<string, object> { { "requestId", request.RequestId }, { "editorSessionId", EditorSessionId() }, { "requestDigest", digest }, { "deadline", request.Execution.AbsoluteDeadlineUtc }, { "phase", "queued" }, { "package", args.Package } };
+                    root["rootContractDigest"] = PackageEmbedRootContractDigest(root);
+                    return root;
+                }
+                protected override void OnTick(Dictionary<string, object> root)
+                {
+                    var phase = Text(root, "phase");
+                    if (phase == "queued")
+                    {
+                        if (BusyEditor()) return;
+                        var method = typeof(UnityEditor.PackageManager.Client).GetMethod("Embed", BindingFlags.Static | BindingFlags.Public);
+                        if (method == null) { Fail(root, "E_PACKAGE_EMBED_UNSUPPORTED", "PackageClient.Embed is not available in this Unity version."); return; }
+                        // Embed 可能在返回前触发 domain reload；fence与post phase确认后才调用effect。
+                        root = CrossEffectFence(root, "package-embed", "embed_started");
+                        try
+                        {
+                            ActiveRequests[Text(root, "requestId")] = method.Invoke(null, new object[] { Text(root, "package") });
+                            Update(x => x["phase"] = "waiting_completed");
+                        }
+                        catch (Exception exception) { Fail(root, "E_PACKAGE_EMBED_FAILED", exception.InnerException == null ? exception.Message : exception.InnerException.Message); }
+                        return;
+                    }
+                    if (phase == "embed_started")
+                    {
+                        // domain reload 后 request 对象已失效，直接转入可持久重建的 PackageInfo/磁盘观察。
+                        Update(x => x["phase"] = "waiting_stable");
+                        return;
+                    }
+                    if (phase == "waiting_completed")
+                    {
+                        object request;
+                        if (!ActiveRequests.TryGetValue(Text(root, "requestId"), out request) || request == null)
+                        {
+                            Update(x => x["phase"] = "waiting_stable");
+                            return;
+                        }
+                        var requestType = request.GetType();
+                        var completed = requestType.GetProperty("IsCompleted");
+                        if (completed == null || !(bool)completed.GetValue(request, null)) return;
+                        var status = requestType.GetProperty("Status");
+                        var value = status == null ? null : status.GetValue(request, null);
+                        if (value != null && string.Equals(value.ToString(), "Failure", StringComparison.OrdinalIgnoreCase))
+                        {
+                            var error = requestType.GetProperty("Error");
+                            var errorValue = error == null ? null : error.GetValue(request, null);
+                            var message = errorValue == null ? null : errorValue.GetType().GetProperty("message")?.GetValue(errorValue, null) as string;
+                            ActiveRequests.Remove(Text(root, "requestId"));
+                            Fail(root, "E_PACKAGE_EMBED_FAILED", string.IsNullOrEmpty(message) ? "Package Manager failed to embed " + Text(root, "package") + "." : message);
+                            return;
+                        }
+                        ActiveRequests.Remove(Text(root, "requestId"));
+                        Update(x => x["phase"] = "waiting_stable");
+                        return;
+                    }
+                    if (phase != "waiting_stable" || BusyEditor()) return;
+                    try { BuildEmbeddedResult(Text(root, "package")); Succeed(root); }
+                    catch (BridgeCommandException) { /* 业务状态尚未稳定，后续 Tick 继续观察。 */ }
+                }
+                protected override object BuildSuccessData(Dictionary<string, object> root) { return BuildEmbeddedResult(Text(root, "package")); }
+                private static bool BusyEditor() { return EditorApplication.isUpdating || EditorApplication.isCompiling || BuildPipeline.isBuildingPlayer || IsPlayModeChanging(); }
+            }
+            private sealed class Args { public string Package { get; set; } }
+            private sealed class Result { public string PackageId { get; set; } public string EmbeddedPath { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+            private static List<EditorPlannedEffect> Effects(string packageId) { return new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "package.embed", Path = packageId } }; }
+            /// <summary>只从 PackageManager registry 与磁盘构造 terminal proof，不触发 resolve/embed。</summary>
+            private static Result BuildEmbeddedResult(string packageId)
+            {
+                var assetPath = "Packages/" + packageId;
+                var info = UnityEditor.PackageManager.PackageInfo.FindForAssetPath(assetPath);
+                var expected = Path.GetFullPath(Path.Combine(Directory.GetParent(Application.dataPath).FullName, "Packages", packageId));
+                var actual = info == null || string.IsNullOrEmpty(info.resolvedPath) ? null : Path.GetFullPath(info.resolvedPath);
+                if (info == null || info.source != UnityEditor.PackageManager.PackageSource.Embedded || !string.Equals(info.name, packageId, StringComparison.Ordinal) || !string.Equals(actual, expected, StringComparison.OrdinalIgnoreCase) || !Directory.Exists(actual))
+                    throw new BridgeCommandException("E_PACKAGE_EMBED_PROOF_MISSING", "Package Manager does not report a verified embedded package at " + assetPath + ".", "Inspect Packages/ and Package Manager diagnostics before submitting a new request.");
+                return new Result { PackageId = packageId, EmbeddedPath = actual, PlannedEffects = Effects(packageId) };
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliPackageResolveCoordinator.cs

@@ -0,0 +1,454 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEditor.PackageManager.Requests;
+using UnityCli.Protocol;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>Package 文件 mutation 与 UPM completion fence 共用一个公开 root journal。</summary>
+        internal static partial class UnityCliPackageResolveCoordinator
+        {
+            internal const string Command = "internal.package.resolve.start";
+            private const string StatusCommand = "internal.package.resolve.status";
+            private const string ClaimFilesCommand = "internal.package.files.claim";
+            private const string CommitFilesCommand = "internal.package.files.commit";
+            private const string ProveFilesCommand = "internal.package.files.prove";
+            private const string FailFilesCommand = "internal.package.files.fail";
+            private const string ReloadEpochScope = "package-reload-epoch";
+            private const string ReloadEpochSessionKey = "UnityCli.Package.ReloadEpoch";
+            private static readonly Dictionary<string, ListRequest> ActiveLists = new Dictionary<string, ListRequest>(StringComparer.Ordinal);
+            private static readonly Coordinator operation = new Coordinator();
+
+            private sealed class Coordinator : UnityCliReloadOperation
+            {
+                protected override string Scope { get { return ActiveScope; } }
+                protected override string StartCommand { get { return Command; } }
+                protected override string StatusCommand { get { return UnityCliPackageResolveCoordinator.StatusCommand; } }
+                protected override string OperationDisplayName { get { return "Package root"; } }
+                protected override IEnumerable<(string name, bool destructive)> AdditionalCommands
+                {
+                    get
+                    {
+                        yield return (ClaimFilesCommand, true);
+                        yield return (CommitFilesCommand, true);
+                        yield return (ProveFilesCommand, true);
+                        yield return (FailFilesCommand, true);
+                    }
+                }
+                protected override object DeserializeStartArgs(BridgeRequest request) { return request.DeserializeArgs<StartArgs>(); }
+                protected override void ValidateStart(object args) { UnityCliPackageResolveCoordinator.ValidateStart((StartArgs)args); }
+                protected override object Planned(object args) { return null; }
+                protected override Dictionary<string, object> CreateRoot(BridgeRequest request, string digest, object args) { return null; }
+                protected override void OnTick(Dictionary<string, object> root) { }
+                protected override object BuildSuccessData(Dictionary<string, object> root) { return null; }
+                protected override object Status(BridgeRequest request) { return UnityCliPackageResolveCoordinator.Status(request); }
+                protected override object ExecuteAdditionalCommand(BridgeRequest request)
+                {
+                    if (request.Command == ClaimFilesCommand) return ClaimFiles(request);
+                    if (request.Command == CommitFilesCommand) return CommitFiles(request);
+                    if (request.Command == ProveFilesCommand) return ProveFiles(request);
+                    if (request.Command == FailFilesCommand) return FailFiles(request);
+                    return base.ExecuteAdditionalCommand(request);
+                }
+                internal override async Task<string> Execute(BridgeRequest request, byte[] raw, Func<bool> accept, CancellationToken cancellationToken)
+                {
+                    try
+                    {
+                        if (request.Command != Command) return await base.Execute(request, raw, accept, cancellationToken);
+                        return await ExecuteStart(request, raw, accept, cancellationToken);
+                    }
+                    catch (BridgeCommandException exception) { return SerializeBridgeExceptionEnvelope(request.RequestId, exception); }
+                }
+                internal override void Tick() { TickPackageRoots(); }
+            }
+
+            internal static bool IsCommand(string command)
+            {
+                return operation.IsCommand(command);
+            }
+
+            internal static void Register(BridgeCommandRegistry registry)
+            {
+                operation.Register(registry);
+            }
+
+            internal static void Initialize() { ActiveLists.Clear(); EnsureReloadEpoch(); RecoverTerminalCleanup(); }
+            internal static void Shutdown() { ActiveLists.Clear(); }
+            internal static void Tick() { RecoverTerminalCleanup(); operation.Tick(); }
+
+            internal static void BeforeReload()
+            {
+                RotateReloadEpoch();
+                ActiveLists.Clear();
+                foreach (var root in OpenRoots())
+                {
+                    var phase = Text(root.PackageOperation, "phase");
+                    if (phase == "awaiting_files" || phase == "files_committing")
+                    {
+                        try
+                        {
+                            UnityCliActiveOperation.Save("package-file-revoke", new Dictionary<string, object>
+                            {
+                                { "requestId", root.RequestId }, { "requestDigest", root.RequestDigest },
+                                { "editorSessionId", root.EditorSessionId }, { "revokedAt", DateTimeOffset.UtcNow.ToString("O", CultureInfo.InvariantCulture) }
+                            });
+                        }
+                        // marker写失败仍必须先冻结terminal，reload后不得接受Worker proof。
+                        catch { }
+                        TerminalTimeout(root, "Domain reload revoked the Package file executor; file effect outcome is unknown.");
+                        continue;
+                    }
+                    if (phase == "files_proven")
+                    {
+                        TerminalTimeout(root, "Domain reload occurred after Package file proof but before Resolve dispatch; continuation is forbidden.");
+                        continue;
+                    }
+                    if (phase == "resolve_dispatching")
+                    {
+                        TerminalTimeout(root, "Domain reload interrupted PackageManager.Resolve dispatch before its return was persisted.");
+                        continue;
+                    }
+                    AdvancePackageOperation(root.RequestId, current =>
+                    {
+                        current.PackageOperation["reloadObserved"] = true;
+                        var currentPhase = Text(current.PackageOperation, "phase");
+                        if (currentPhase == "resolve_returned" || currentPhase == "list_pending" || currentPhase == "list_succeeded") current.PackageOperation["phase"] = "reload_observed";
+                        current.PackageOperation["reloadEpoch"] = CurrentReloadEpoch();
+                    });
+                }
+            }
+
+            internal static async Task<string> Execute(BridgeRequest request, byte[] raw, Func<bool> accept, CancellationToken cancellationToken)
+            {
+                return await operation.Execute(request, raw, accept, cancellationToken);
+            }
+
+            private static async Task<string> ExecuteStart(BridgeRequest request, byte[] raw, Func<bool> accept, CancellationToken cancellationToken)
+            {
+                var newlyAcquiredLease = false;
+                var requestDigest = UnityCliRequestDigest.Compute(raw, request.InstanceId);
+                try
+                {
+                    var args = request.DeserializeArgs<StartArgs>();
+                    ValidateStart(args);
+                    object cachedTerminal;
+                    if (UnityCliActiveOperation.TryGetTerminal(ActiveScope, request.RequestId, requestDigest, out cachedTerminal))
+                    {
+                        try { UnityCliActiveOperation.BeginExactTerminalCleanup(ActiveScope, request.RequestId, requestDigest); } catch { }
+                        return StartTerminal(request.RequestId, cachedTerminal);
+                    }
+                    if (!UnityCliSessionMutationLease.TryAcquire(request.RequestId, requestDigest, out newlyAcquiredLease)) return BusyEnvelope(request.RequestId);
+                    PackageActiveDecision decision;
+                    try
+                    {
+                        UnityCliToolCompletionContract contract;
+                        if (!UnityCliToolCompletionRegistry.TryGetPackageRoot(args.Operation, out contract)) throw new BridgeCommandException("E_SCHEMA_INVALID", "Unsupported package root operation.");
+                        decision = AcceptPackageActiveOperation(request, raw, contract, newlyAcquiredLease,
+                            () => { if (accept == null || !accept()) throw new OperationCanceledException(); },
+                            () => ValidateStart(args), root => InitializeRoot(root, args));
+                    }
+                    catch { if (newlyAcquiredLease) UnityCliSessionMutationLease.Release(request.RequestId, requestDigest); throw; }
+                    if (decision.TerminalEnvelope != null)
+                    {
+                        UnityCliSessionMutationLease.Release(request.RequestId, requestDigest);
+                        return StartTerminal(request.RequestId, decision.TerminalEnvelope);
+                    }
+                    if (!decision.Execute)
+                    {
+                        if (newlyAcquiredLease) UnityCliSessionMutationLease.Release(request.RequestId, requestDigest);
+                        throw new BridgeCommandException("E_EXECUTION_TIMEOUT", "Package active operation did not authorize recovery.");
+                    }
+                    await Task.FromResult(0);
+                    return UnityCliSerializer.Serialize(StartState(request.RequestId));
+                }
+                catch (BridgeCommandException exception) { return SerializeBridgeExceptionEnvelope(request.RequestId, exception); }
+            }
+
+            private static string CurrentReloadEpoch()
+            {
+                var epoch = SessionState.GetString(ReloadEpochSessionKey, string.Empty);
+                if (string.IsNullOrEmpty(epoch)) { epoch = Guid.NewGuid().ToString("N"); SessionState.SetString(ReloadEpochSessionKey, epoch); }
+                return epoch;
+            }
+
+            private static void EnsureReloadEpoch()
+            {
+                var epoch = CurrentReloadEpoch();
+                try
+                {
+                    UnityCliActiveOperation.Save(ReloadEpochScope, new Dictionary<string, object>
+                    {
+                        { "editorSessionId", EditorSessionId() }, { "epoch", epoch }
+                    });
+                }
+                catch { }
+            }
+
+            private static void RotateReloadEpoch()
+            {
+                var epoch = Guid.NewGuid().ToString("N");
+                SessionState.SetString(ReloadEpochSessionKey, epoch);
+                try { UnityCliActiveOperation.Clear(ReloadEpochScope); } catch { }
+                EnsureReloadEpoch();
+            }
+
+            private static void RecoverTerminalCleanup()
+            {
+                try
+                {
+                    if (UnityCliActiveOperation.RetryExactTerminalCleanup(ActiveScope)) return;
+                    var root = LoadPackageActiveOperation();
+                    if (root == null) return;
+                    object terminal;
+                    if (!UnityCliActiveOperation.TryGetTerminal(ActiveScope, root.RequestId, root.RequestDigest, out terminal)
+                        && root.TerminalEnvelope != null)
+                    {
+                        var selector = UnityCliSerializer.Sha256Canonical(root.PackageOperation["input"]);
+                        terminal = UnityCliActiveOperation.StoreTerminalFirst(ActiveScope, root.RequestId, root.RequestDigest, selector, root.TerminalEnvelope);
+                    }
+                    if (terminal != null) UnityCliActiveOperation.BeginExactTerminalCleanup(ActiveScope, root.RequestId, root.RequestDigest);
+                }
+                catch { RecoverCorruptPackageRoot(); }
+            }
+
+            private static void RecoverCorruptPackageRoot()
+            {
+                try
+                {
+                    string requestId;
+                    string requestDigest;
+                    if (!UnityCliSessionMutationLease.TryGetOnlyActiveScopeOwner(ActiveScope, out requestId, out requestDigest)) return;
+                    var envelope = ProtocolEnvelopeFactory.Error(requestId, "E_EXECUTION_TIMEOUT", "Package active state is corrupt or unreadable; file and Resolve outcome is unknown.", null, new[] { "Inspect Package Manager and package files before submitting another mutation." });
+                    UnityCliActiveOperation.StoreTerminalFirst(ActiveScope, requestId, requestDigest, envelope);
+                    UnityCliActiveOperation.BeginExactTerminalCleanup(ActiveScope, requestId, requestDigest);
+                }
+                catch { }
+            }
+
+            /// <summary>effect 前先持久化唯一 file executor；只有旧 owner 已死亡时才允许 recovery 重绑。</summary>
+            private static object ClaimFiles(BridgeRequest request)
+            {
+                var args = request.DeserializeArgs<FileOwnerArgs>();
+                if (args == null || !IsSafeId(args.RootRequestId) || args.ExecutorPid <= 0 || !IsSha256Text(args.ExecutorCapability)) throw Schema("rootRequestId, executorPid, and executorCapability are required.");
+                var root = RequiredRoot(args.RootRequestId);
+                var operation = Text(root.PackageOperation, "operation");
+                if (operation == "resolve") throw Schema("package.resolve has no TS file executor.");
+                RequireLease(root);
+                if (Text(root.PackageOperation, "phase") != "awaiting_files" || root.Phase != "accepted_before_effect")
+                    throw new BridgeCommandException("E_EXECUTION_FAILED", "Package root is not awaiting a file executor claim.");
+                if (FileExecutorMatches(root.PackageOperation, args.ExecutorPid, args.ExecutorCapability))
+                    return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+                if (FileExecutorAlive(root.PackageOperation))
+                    return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+                BindFileExecutor(root.RequestId, args.ExecutorPid, args.ExecutorCapability);
+                return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(RequiredRoot(root.RequestId), args.ExecutorPid, args.ExecutorCapability));
+            }
+
+            private static object CommitFiles(BridgeRequest request)
+            {
+                var args = request.DeserializeArgs<CommitArgs>();
+                if (args == null || !IsSafeId(args.RootRequestId) || args.FilePlan == null || args.ExecutorPid <= 0 || !IsSha256Text(args.ExecutorCapability)) throw Schema("rootRequestId, filePlan, executorPid, and executorCapability are required.");
+                if (Encoding.UTF8.GetByteCount(UnityCliSerializer.Serialize(args.FilePlan)) > 1024 * 1024) throw Schema("Package filePlan exceeds the private journal limit.");
+                var root = RequiredRoot(args.RootRequestId);
+                var operation = Text(root.PackageOperation, "operation");
+                if (operation == "resolve") throw Schema("package.resolve has no TS file mutation.");
+                VerifyFilePlanBinding(operation, root.PackageOperation["input"] as Dictionary<string, object>, args.FilePlan);
+                RequireLease(root);
+                var phase = Text(root.PackageOperation, "phase");
+                if (phase == "files_committing")
+                {
+                    if (!SameJson(root.PackageOperation["filePlan"], args.FilePlan)) throw new BridgeCommandException("E_EXECUTION_FAILED", "Package filePlan changed after effect barrier.");
+                    if (FileExecutorMatches(root.PackageOperation, args.ExecutorPid, args.ExecutorCapability)) return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+                    if (FileExecutorAlive(root.PackageOperation)) throw new BridgeCommandException("E_UNITY_BUSY", "Another Package file executor still owns this root.");
+                    BindFileExecutor(root.RequestId, args.ExecutorPid, args.ExecutorCapability);
+                    return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(RequiredRoot(root.RequestId), args.ExecutorPid, args.ExecutorCapability));
+                }
+                if (phase != "awaiting_files" || root.Phase != "accepted_before_effect") throw new BridgeCommandException("E_EXECUTION_FAILED", "Package root is not awaiting its file effect barrier.");
+                if (root.PackageOperation.ContainsKey("filePlan")) throw new BridgeCommandException("E_EXECUTION_FAILED", "Package root contains a file plan before its atomic effect barrier.");
+                RequireFileExecutor(root.PackageOperation, args.ExecutorPid, args.ExecutorCapability);
+                MarkPackageFileEffectStartedActive(root.RequestId, args.FilePlan, Text(root.PackageOperation, "operation"));
+                return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(RequiredRoot(root.RequestId), args.ExecutorPid, args.ExecutorCapability));
+            }
+
+            private static object ProveFiles(BridgeRequest request)
+            {
+                var args = request.DeserializeArgs<ProveArgs>();
+                ValidateProve(args);
+                var root = RequiredRoot(args.RootRequestId);
+                var operation = Text(root.PackageOperation, "operation");
+                if (operation == "resolve") throw Schema("package.resolve has no TS file proof.");
+                RequireLease(root);
+                RequireFileExecutor(root.PackageOperation, args.ExecutorPid, args.ExecutorCapability);
+                var phase = Text(root.PackageOperation, "phase");
+                if (phase != "files_committing")
+                {
+                    if (phase != "awaiting_files" && root.PackageOperation.ContainsKey("filesProof")) return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+                    throw new BridgeCommandException("E_EXECUTION_FAILED", "Package root is not awaiting file proof.");
+                }
+                VerifyFileProof(Text(root.PackageOperation, "operation"), args.ExpectedManifestSha256, args.FilesProof, args.PublicResultSeed);
+                AdvancePackageOperation(root.RequestId, current =>
+                {
+                    current.PackageOperation["expectedManifestSha256"] = args.ExpectedManifestSha256;
+                    current.PackageOperation["predicates"] = args.Predicates != null ? (object)args.Predicates : new List<Dictionary<string, object>>();
+                    current.PackageOperation["filesProof"] = args.FilesProof;
+                    current.PackageOperation["publicResultSeed"] = args.PublicResultSeed;
+                    current.PackageOperation["phase"] = "files_proven";
+                });
+                return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(RequiredRoot(root.RequestId), args.ExecutorPid, args.ExecutorCapability));
+            }
+
+            private static object FailFiles(BridgeRequest request)
+            {
+                var args = request.DeserializeArgs<FailArgs>();
+                if (args == null || !IsSafeId(args.RootRequestId) || args.ExecutorPid <= 0 || !IsSha256Text(args.ExecutorCapability)) throw Schema("rootRequestId, executorPid, and executorCapability are required.");
+                var root = RequiredRoot(args.RootRequestId);
+                var operation = Text(root.PackageOperation, "operation");
+                var phase = Text(root.PackageOperation, "phase");
+                if (phase != "awaiting_files" && phase != "files_committing") return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+                RequireLease(root);
+                RequireFileExecutor(root.PackageOperation, args.ExecutorPid, args.ExecutorCapability);
+                if (PackageEffectStarted(root.RequestId)) TerminalTimeout(root, string.IsNullOrWhiteSpace(args.Message) ? "Package file mutation did not reach fresh proof." : args.Message);
+                else TerminalError(root, string.IsNullOrWhiteSpace(args.Code) ? "E_EXECUTION_FAILED" : args.Code, string.IsNullOrWhiteSpace(args.Message) ? "Package file preparation failed." : args.Message, null, args.NextActions);
+                return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(RequiredRoot(root.RequestId), args.ExecutorPid, args.ExecutorCapability));
+            }
+
+            private static object Status(BridgeRequest request)
+            {
+                var args = request.DeserializeArgs<StatusArgs>();
+                if (args == null || !IsSafeId(args.RootRequestId) || !IsSha256Text(args.RootInputSha256)
+                    || (!string.IsNullOrEmpty(args.RootRequestDigest) && !IsSha256Text(args.RootRequestDigest))
+                    || args.ExecutorPid <= 0 || !IsSha256Text(args.ExecutorCapability)) throw Schema("rootRequestId, rootInputSha256, executorPid, and executorCapability are required.");
+                object cached;
+                var found = !string.IsNullOrEmpty(args.RootRequestDigest)
+                    ? UnityCliActiveOperation.TryGetTerminal(ActiveScope, args.RootRequestId, args.RootRequestDigest, out cached)
+                    : UnityCliActiveOperation.TryGetTerminalBySelector(ActiveScope, args.RootRequestId, args.RootInputSha256, out cached);
+                if (found) return ProtocolEnvelopeFactory.Success(request.RequestId, new Dictionary<string, object>
+                {
+                    { "accepted", true }, { "terminal", true }, { "rootInputSha256", args.RootInputSha256 }, { "terminalEnvelope", cached }
+                });
+                var root = RequiredRoot(args.RootRequestId);
+                if (!string.Equals(UnityCliSerializer.Sha256Canonical(root.PackageOperation["input"]), args.RootInputSha256, StringComparison.Ordinal)
+                    || (!string.IsNullOrEmpty(args.RootRequestDigest) && !string.Equals(root.RequestDigest, args.RootRequestDigest, StringComparison.Ordinal)))
+                    throw new BridgeCommandException("E_REQUEST_ID_REUSED", "Package requestId was reused with different input.");
+                return ProtocolEnvelopeFactory.Success(request.RequestId, ControlState(root, args.ExecutorPid, args.ExecutorCapability));
+            }
+
+            private static Dictionary<string, object> ControlState(ActivePackageOperationRecord root, int callerPid = 0, string callerCapability = null)
+            {
+                var data = new Dictionary<string, object> {
+                    { "accepted", true }, { "terminal", IsTerminal(root) }, { "phase", Text(root.PackageOperation, "phase") }, { "rootRequestDigest", root.RequestDigest },
+                    { "operation", Text(root.PackageOperation, "operation") }, { "rootInputSha256", UnityCliSerializer.Sha256Canonical(root.PackageOperation["input"]) },
+                    { "fileExecutorAlive", FileExecutorAlive(root.PackageOperation) },
+                    { "fileExecutorOwnedByCaller", callerPid > 0 && FileExecutorMatches(root.PackageOperation, callerPid, callerCapability) }
+                };
+                if (root.PackageOperation.ContainsKey("filePlan")) data["filePlan"] = root.PackageOperation["filePlan"];
+                if (root.TerminalEnvelope != null) data["terminalEnvelope"] = root.TerminalEnvelope;
+                return data;
+            }
+
+            private static object StartState(string requestId)
+            {
+                var root = RequiredRoot(requestId);
+                var data = ControlState(root);
+                data["requestId"] = requestId;
+                return ProtocolEnvelopeFactory.Success(requestId, data);
+            }
+
+            private static string StartTerminal(string requestId, object terminalEnvelope)
+            {
+                return UnityCliSerializer.Serialize(ProtocolEnvelopeFactory.Success(requestId, new Dictionary<string, object> { { "requestId", requestId }, { "accepted", true }, { "terminal", true }, { "terminalEnvelope", terminalEnvelope } }));
+            }
+
+            private sealed class StartArgs { public string ExpectedEditorSessionId { get; set; } public string Operation { get; set; } public Dictionary<string, object> Input { get; set; } }
+            private sealed class StatusArgs { public string RootRequestId { get; set; } public string RootRequestDigest { get; set; } public string RootInputSha256 { get; set; } public int ExecutorPid { get; set; } public string ExecutorCapability { get; set; } }
+            private sealed class FileOwnerArgs { public string RootRequestId { get; set; } public int ExecutorPid { get; set; } public string ExecutorCapability { get; set; } }
+            private static bool FileExecutorAlive(Dictionary<string, object> operation)
+            {
+                object pidValue; object identityValue;
+                if (operation == null || !operation.TryGetValue("fileExecutorPid", out pidValue) || !operation.TryGetValue("fileExecutorStartIdentity", out identityValue)) return false;
+                var pid = Convert.ToInt32(pidValue);
+                return string.Equals(ProcessIdentity(pid), identityValue as string, StringComparison.Ordinal);
+            }
+            /// <summary>PID、Windows start identity 与高熵 capability 必须同时等于 durable owner。</summary>
+            private static bool FileExecutorMatches(Dictionary<string, object> operation, int pid, string capability)
+            {
+                object pidValue; object identityValue; object capabilityHashValue;
+                return operation != null && IsSha256Text(capability)
+                    && operation.TryGetValue("fileExecutorPid", out pidValue) && Convert.ToInt32(pidValue) == pid
+                    && operation.TryGetValue("fileExecutorStartIdentity", out identityValue)
+                    && string.Equals(ProcessIdentity(pid), identityValue as string, StringComparison.Ordinal)
+                    && operation.TryGetValue("fileExecutorCapabilitySha256", out capabilityHashValue)
+                    && string.Equals(Sha256Hex(Encoding.UTF8.GetBytes(capability)), capabilityHashValue as string, StringComparison.Ordinal);
+            }
+            /// <summary>校验 file control 的不可伪造 owner capability，拒绝其他本地进程代为证明或裁决。</summary>
+            private static void RequireFileExecutor(Dictionary<string, object> operation, int pid, string capability)
+            {
+                if (pid <= 0 || !FileExecutorMatches(operation, pid, capability)) throw new BridgeCommandException("E_PACKAGE_FILE_EXECUTOR_MISMATCH", "Package file control is not owned by the current executor process.");
+            }
+            /// <summary>仅在旧 executor 已证明不存活后，把 recovery PID、identity 与 capability hash 原子写回 root。</summary>
+            private static void BindFileExecutor(string requestId, int pid, string capability)
+            {
+                if (!IsSha256Text(capability)) throw Schema("executorCapability must be 256-bit lowercase hex.");
+                var identity = RequireProcessIdentity(pid);
+                var capabilityHash = Sha256Hex(Encoding.UTF8.GetBytes(capability));
+                AdvancePackageOperation(requestId, current =>
+                {
+                    current.PackageOperation["fileExecutorPid"] = (long)pid;
+                    current.PackageOperation["fileExecutorStartIdentity"] = identity;
+                    current.PackageOperation["fileExecutorCapabilitySha256"] = capabilityHash;
+                });
+            }
+            /// <summary>读取 fail-closed Windows process identity，无法证明时禁止推进 root。</summary>
+            private static string RequireProcessIdentity(int pid)
+            {
+                var identity = ProcessIdentity(pid);
+                if (identity == null) throw new BridgeCommandException("E_EXECUTION_FAILED", "Package file executor identity could not be verified before changing root state.");
+                return identity;
+            }
+            /// <summary>file plan 必须逐字段绑定 root 的公开输入，不能由 private control 换成另一项业务 mutation。</summary>
+            private static void VerifyFilePlanBinding(string operation, Dictionary<string, object> rootInput, Dictionary<string, object> filePlan)
+            {
+                var matches = rootInput != null && filePlan != null;
+                if (matches && operation == "install")
+                    matches = Same(Text(rootInput, "name"), Text(filePlan, "name")) && Same(Text(rootInput, "version"), Text(filePlan, "version"));
+                else if (matches && operation == "remove")
+                    matches = Same(Text(rootInput, "name"), Text(filePlan, "name")) && Bool(rootInput, "force") == Bool(filePlan, "force");
+                else if (matches && operation == "deploy")
+                    matches = Same(Text(rootInput, "source"), Text(filePlan, "requestedSource"))
+                        && OptionalSame(Text(rootInput, "packageName"), Text(filePlan, "requestedPackageName"));
+                else if (matches && operation == "restore")
+                    matches = Same(Text(rootInput, "packageName"), Text(filePlan, "packageName"));
+                else matches = false;
+                if (!matches) throw new BridgeCommandException("E_EXECUTION_FAILED", "Package filePlan is not bound to the accepted public root input.");
+            }
+
+            /// <summary>可选字符串只有双 null 或双非空精确相等时才匹配。</summary>
+            private static bool OptionalSame(string left, string right)
+            {
+                return left == null ? right == null : Same(left, right);
+            }
+
+            private static string ProcessIdentity(int pid)
+            {
+                try { using (var process = Process.GetProcessById(pid)) return "win32:" + process.StartTime.ToUniversalTime().Ticks.ToString(System.Globalization.CultureInfo.InvariantCulture); }
+                catch { return null; }
+            }
+
+            private sealed class CommitArgs { public string RootRequestId { get; set; } public Dictionary<string, object> FilePlan { get; set; } public int ExecutorPid { get; set; } public string ExecutorCapability { get; set; } }
+            private sealed class ProveArgs { public string RootRequestId { get; set; } public int ExecutorPid { get; set; } public string ExecutorCapability { get; set; } public string ExpectedManifestSha256 { get; set; } public List<Dictionary<string, object>> Predicates { get; set; } public Dictionary<string, object> FilesProof { get; set; } public Dictionary<string, object> PublicResultSeed { get; set; } }
+            private sealed class FailArgs { public string RootRequestId { get; set; } public int ExecutorPid { get; set; } public string ExecutorCapability { get; set; } public string Code { get; set; } public string Message { get; set; } public string[] NextActions { get; set; } }
+        }
+    }
+}
+#endif