using ZB.MOM.WW.ScadaBridge.Commons.Types;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.ScriptAnalysis;

/// <summary>
/// Runtime globals for the Test Run sandbox. Mirrors the real site-runtime
/// <c>ScriptGlobals</c> surface (ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts) member-for-member
/// so the same user code that runs at a site also compiles and runs here.
///
/// Instance-context members — <c>Instance.GetAttribute/SetAttribute/CallScript</c>,
/// <c>Attributes</c>, <c>Children</c>, <c>Parent</c> — need a live deployed
/// instance. With no instance bound they throw <see cref="ScriptSandboxException"/>;
/// with one bound (see <see cref="SandboxInstanceContext"/>) they route to it.
///
/// <c>ExternalSystem</c>, <c>Database</c>, and <c>Scripts.CallShared</c> run
/// against central's real services and fire for real; <c>Notify</c> is a
/// signature-faithful no-op fake. None of them depend on a bound instance.
/// </summary>
public class SandboxScriptHost
{
    /// <summary>
    /// Script parameters passed to the sandbox.
    /// </summary>
    public ScriptParameters Parameters { get; init; } = new();

    /// <summary>
    /// Cancellation token for the sandbox execution.
    /// </summary>
    public CancellationToken CancellationToken { get; init; }

    /// <summary>
    /// Alarm context for the sandbox.
    /// </summary>
    public AlarmContext? Alarm { get; init; }

    /// <summary>
    /// Script scope defining the execution context.
    /// </summary>
    public ScriptScope Scope { get; init; } = ScriptScope.Root;

    /// <summary>
    /// Instance context providing access to deployed instance data.
    /// </summary>
    public SandboxInstanceContext Instance { get; init; } = new();

    /// <summary>
    /// Helper for external system calls.
    /// </summary>
    public SandboxExternalHelper ExternalSystem => Instance.ExternalSystem;

    /// <summary>
    /// Helper for database operations.
    /// </summary>
    public SandboxDatabaseHelper Database => Instance.Database;

    /// <summary>
    /// Helper for sending notifications.
    /// </summary>
    public SandboxNotifyHelper Notify => Instance.Notify;

    /// <summary>
    /// Helper for calling scripts.
    /// </summary>
    public SandboxScriptCallHelper Scripts => Instance.Scripts;

    /// <summary>
    /// Accessor for attributes scoped to the current instance.
    /// </summary>
    public SandboxAttributeAccessor Attributes => new(Instance, Scope.SelfPath);

    /// <summary>
    /// Accessor for child compositions.
    /// </summary>
    public SandboxChildrenAccessor Children => new(Instance, Scope.SelfPath);

    /// <summary>
    /// Accessor for the parent composition, or null if at root.
    /// </summary>
    public SandboxCompositionAccessor? Parent =>
        Scope.ParentPath == null ? null : new SandboxCompositionAccessor(Instance, Scope.ParentPath);

    /// <summary>
    /// Read-only accessor for the instance's current alarm conditions, mirroring the site
    /// runtime's <c>Alarms</c> global (MES alarm-status API §5.2). Present so a script using
    /// <c>Alarms.CurrentAsync()</c> BINDS in the Test Run editor — without it the editor
    /// would show a spurious CS1061 on a script that deploys and runs perfectly.
    /// </summary>
    public SandboxAlarmsAccessor Alarms { get; } = new();

    /// <summary>
    /// Sandbox mirror of the site runtime's <c>Log</c> global (step logs design 2026-09-09 D4).
    /// Present so a script that logs BINDS in the Test Run editor; lines go to the Test Run
    /// console pane and are never audited. Delegates to <see cref="SandboxInstanceContext.Log"/>
    /// exactly as the runtime's <c>ScriptGlobals.Log =&gt; Instance.Log</c> does, so
    /// <c>Log</c> and <c>Instance.Log</c> are the same object here too.
    /// </summary>
    public SandboxLog Log => Instance.Log;
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.ScriptLogger</c> (step logs
/// design 2026-09-09 D4). Signature-faithful so the same script body compiles here and at a site,
/// but a Test Run has no execution to trace and no audit trail: every line is written to
/// <see cref="Console.Out"/>, which the sandbox captures into
/// <c>SandboxRunResult.ConsoleOutput</c> (see <see cref="SandboxConsoleCapture"/>) and shows in
/// the editor's console pane. Nothing here reaches the node log or the audit log.
/// </summary>
public class SandboxLog
{
    /// <summary>Writes a debug-level line to the Test Run console pane.</summary>
    /// <param name="message">The message text.</param>
    /// <param name="exception">An optional exception, rendered on a following line.</param>
    public void Debug(string message, Exception? exception = null) => Write("debug", message, exception);

    /// <summary>Writes an information-level line to the Test Run console pane.</summary>
    /// <param name="message">The message text.</param>
    /// <param name="exception">An optional exception, rendered on a following line.</param>
    public void Info(string message, Exception? exception = null) => Write("info", message, exception);

    /// <summary>Writes a warning-level line to the Test Run console pane.</summary>
    /// <param name="message">The message text.</param>
    /// <param name="exception">An optional exception, rendered on a following line.</param>
    public void Warn(string message, Exception? exception = null) => Write("warn", message, exception);

    /// <summary>
    /// Writes an error-level line to the Test Run console pane. Like the runtime logger, this
    /// does NOT fail the run — it is a message, not a throw.
    /// </summary>
    /// <param name="message">The message text.</param>
    /// <param name="exception">An optional exception, rendered on a following line.</param>
    public void Error(string message, Exception? exception = null) => Write("error", message, exception);

    private static void Write(string level, string message, Exception? exception)
    {
        Console.Out.WriteLine($"[{level}] {message}");
        if (exception != null)
        {
            Console.Out.WriteLine(exception.ToString());
        }
    }
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.AlarmsAccessor</c>.
/// Exists for editor/compile parity only: alarm state is held per-instance by the site's
/// Instance Actor and there is no central Test Run route to it, so an actual call throws a
/// clearly-labelled <see cref="ScriptSandboxException"/> rather than quietly returning an
/// empty list that would read as "nothing is in alarm".
/// </summary>
public class SandboxAlarmsAccessor
{
    /// <summary>
    /// Mirrors <c>AlarmsAccessor.CurrentAsync</c> for compile parity; unsupported at run
    /// time in the central Test Run sandbox.
    /// </summary>
    /// <param name="cancellationToken">Token used to cancel the read (unused in the sandbox).</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<IReadOnlyList<ScriptAlarm>> CurrentAsync(CancellationToken cancellationToken = default)
        => throw new ScriptSandboxException(
            "Alarms.CurrentAsync() reads the site Instance Actor's live alarm conditions, " +
            "which aren't available in the central Test Run sandbox — deploy to a site to " +
            "exercise alarm-reading scripts.");

    /// <summary>
    /// Mirrors <c>AlarmsAccessor.MesReportableAsync</c> for compile parity; unsupported at
    /// run time in the central Test Run sandbox.
    /// </summary>
    /// <param name="cancellationToken">Token used to cancel the read (unused in the sandbox).</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<IReadOnlyList<ScriptAlarm>> MesReportableAsync(CancellationToken cancellationToken = default)
        => throw new ScriptSandboxException(
            "Alarms.MesReportableAsync() reads the site Instance Actor's live alarm conditions, " +
            "which aren't available in the central Test Run sandbox — deploy to a site to " +
            "exercise alarm-reading scripts.");
}

/// <summary>
/// Backs the sandbox <c>Instance</c> when a Test Run is bound to a real
/// deployed instance. Null when unbound. The implementation routes to the
/// instance cross-site over the cluster transport.
/// </summary>
public interface ISandboxInstanceGateway
{
    /// <summary>
    /// Gets the value of an attribute with the specified canonical name.
    /// </summary>
    /// <param name="canonicalName">The canonical name of the attribute.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The attribute value, or null if not found.</returns>
    Task<object?> GetAttributeAsync(string canonicalName, CancellationToken ct);

    /// <summary>
    /// Sets the value of an attribute with the specified canonical name.
    /// </summary>
    /// <param name="canonicalName">The canonical name of the attribute.</param>
    /// <param name="value">The value to set.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task SetAttributeAsync(string canonicalName, string value, CancellationToken ct);

    /// <summary>
    /// Calls a script with the specified canonical name.
    /// </summary>
    /// <param name="canonicalScriptName">The canonical name of the script.</param>
    /// <param name="parameters">Script parameters, or null if none.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The script result, or null if none.</returns>
    Task<object?> CallScriptAsync(
        string canonicalScriptName, IReadOnlyDictionary<string, object?>? parameters, CancellationToken ct);

    /// <summary>
    /// Blocks until the named attribute reaches a target value (value-equality,
    /// codec-encoded), optionally quality-gated, or the timeout elapses — routed to the
    /// bound deployed instance cross-site. Value-equality only: a script-side predicate
    /// cannot be routed, so the sandbox predicate overloads stay unsupported.
    /// </summary>
    /// <param name="canonicalName">The (already scope-resolved) canonical attribute name.</param>
    /// <param name="targetValueEncoded">The <c>AttributeValueCodec</c>-encoded target value, or null for "any change".</param>
    /// <param name="timeout">Maximum time to wait.</param>
    /// <param name="requireGoodQuality">When true, only a Good-quality value satisfies the wait.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The wait outcome (matched flag, matched value, quality, timed-out flag).</returns>
    Task<WaitResult> WaitForAttributeAsync(
        string canonicalName, string? targetValueEncoded, TimeSpan timeout, bool requireGoodQuality, CancellationToken ct);
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.ScriptRuntimeContext</c> —
/// the <c>Instance</c> global. Attribute and sibling-script access needs a real
/// deployed instance: with no gateway wired it throws; with one (a bound
/// instance) it routes cross-site. <c>ExternalSystem</c>/<c>Database</c>/
/// <c>Scripts</c> run against central's real services regardless of binding;
/// <c>Notify</c> is a signature-faithful no-op fake.
/// </summary>
public class SandboxInstanceContext
{
    private readonly ISandboxInstanceGateway? _gateway;

    /// <summary>
    /// Helper for external system calls.
    /// </summary>
    public SandboxExternalHelper ExternalSystem { get; }

    /// <summary>
    /// Helper for database operations.
    /// </summary>
    public SandboxDatabaseHelper Database { get; }

    /// <summary>
    /// Helper for sending notifications.
    /// </summary>
    public SandboxNotifyHelper Notify { get; }

    /// <summary>
    /// Helper for calling scripts.
    /// </summary>
    public SandboxScriptCallHelper Scripts { get; }

    /// <summary>
    /// Sandbox mirror of <c>ScriptRuntimeContext.Log</c> (step logs design 2026-09-09 D4), so
    /// <c>Instance.Log.Info("…")</c> binds and prints in the Test Run console pane.
    /// </summary>
    public SandboxLog Log { get; } = new();

    /// <summary>
    /// Initializes a new instance of the SandboxInstanceContext.
    /// </summary>
    /// <param name="gateway">Gateway for accessing deployed instance data, or null if unbound.</param>
    /// <param name="external">External system helper, or null to create a default.</param>
    /// <param name="database">Database helper, or null to create a default.</param>
    /// <param name="notify">Notification helper, or null to create a default.</param>
    /// <param name="scripts">Script call helper, or null to create a default.</param>
    public SandboxInstanceContext(
        ISandboxInstanceGateway? gateway = null,
        SandboxExternalHelper? external = null,
        SandboxDatabaseHelper? database = null,
        SandboxNotifyHelper? notify = null,
        SandboxScriptCallHelper? scripts = null)
    {
        _gateway = gateway;
        ExternalSystem = external ?? new SandboxExternalHelper(null, "<sandbox>");
        Database = database ?? new SandboxDatabaseHelper(null, "<sandbox>");
        Notify = notify ?? new SandboxNotifyHelper();
        Scripts = scripts ?? new SandboxScriptCallHelper(null);
    }

    /// <summary>
    /// Gets the value of an attribute.
    /// </summary>
    /// <param name="attributeName">The name of the attribute.</param>
    /// <returns>The attribute value, or null if not found.</returns>
    public Task<object?> GetAttribute(string attributeName)
    {
        if (_gateway == null)
            throw new ScriptSandboxException(
                $"GetAttribute(\"{attributeName}\") needs a deployed instance — " +
                "bind one in Test Run to read live attribute values.");
        return _gateway.GetAttributeAsync(attributeName, CancellationToken.None);
    }

    /// <summary>
    /// Sets the value of an attribute.
    /// </summary>
    /// <param name="attributeName">The name of the attribute.</param>
    /// <param name="value">The value to set.</param>
    public void SetAttribute(string attributeName, string value)
    {
        if (_gateway == null)
            throw new ScriptSandboxException(
                $"SetAttribute(\"{attributeName}\") needs a deployed instance — " +
                "bind one in Test Run to write attribute values.");
        _gateway.SetAttributeAsync(attributeName, value, CancellationToken.None).GetAwaiter().GetResult();
    }

    /// <summary>
    /// Calls a sibling script.
    /// </summary>
    /// <param name="scriptName">The name of the script.</param>
    /// <param name="parameters">Script parameters, or null if none.</param>
    /// <returns>The script result, or null if none.</returns>
    public Task<object?> CallScript(string scriptName, object? parameters = null)
    {
        if (_gateway == null)
            throw new ScriptSandboxException(
                $"CallScript(\"{scriptName}\") needs a deployed instance — " +
                "bind one in Test Run to call sibling scripts.");
        return _gateway.CallScriptAsync(scriptName, ScriptArgs.Normalize(parameters), CancellationToken.None);
    }

    /// <summary>
    /// Routes a value-equality attribute wait to the bound deployed instance cross-site.
    /// Needs a bound instance (the site owns the event-driven waiter); throws when unbound.
    /// </summary>
    /// <param name="canonicalName">The (already scope-resolved) canonical attribute name.</param>
    /// <param name="targetValueEncoded">The codec-encoded target value, or null for "any change".</param>
    /// <param name="timeout">Maximum time to wait.</param>
    /// <param name="requireGoodQuality">When true, only a Good-quality value satisfies the wait.</param>
    /// <returns>The wait outcome.</returns>
    public Task<WaitResult> WaitForAttribute(
        string canonicalName, string? targetValueEncoded, TimeSpan timeout, bool requireGoodQuality)
    {
        if (_gateway == null)
            throw new ScriptSandboxException(
                $"WaitForAttribute(\"{canonicalName}\") needs a deployed instance — " +
                "bind one in Test Run to exercise the event-driven attribute waiter.");
        return _gateway.WaitForAttributeAsync(
            canonicalName, targetValueEncoded, timeout, requireGoodQuality, CancellationToken.None);
    }
}

/// <summary>
/// Sandbox mirror of <c>ScriptRuntimeContext.ScriptCallHelper</c> —
/// <c>Scripts.CallShared(...)</c>. Compiles and runs the named shared script in
/// the same sandbox via the wired delegate.
/// </summary>
public class SandboxScriptCallHelper
{
    private readonly Func<string, IReadOnlyDictionary<string, object?>?, CancellationToken, Task<object?>>? _callShared;

    /// <summary>
    /// Initializes a new instance of the SandboxScriptCallHelper.
    /// </summary>
    /// <param name="callShared">Delegate for calling shared scripts, or null if not available.</param>
    public SandboxScriptCallHelper(
        Func<string, IReadOnlyDictionary<string, object?>?, CancellationToken, Task<object?>>? callShared)
    {
        _callShared = callShared;
    }

    /// <summary>
    /// Calls a shared script.
    /// </summary>
    /// <param name="scriptName">The name of the shared script.</param>
    /// <param name="parameters">Script parameters, or null if none.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The script result, or null if none.</returns>
    public Task<object?> CallShared(
        string scriptName,
        object? parameters = null,
        CancellationToken cancellationToken = default)
    {
        if (_callShared == null)
            throw new ScriptSandboxException(
                $"Scripts.CallShared(\"{scriptName}\") — shared-script catalog not configured for Test Run.");
        return _callShared(scriptName, ScriptArgs.Normalize(parameters), cancellationToken);
    }
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.AttributeAccessor</c> —
/// scope-aware <c>Attributes["X"]</c> access anchored at a canonical-name prefix.
/// </summary>
public class SandboxAttributeAccessor
{
    private readonly SandboxInstanceContext _ctx;

    /// <summary>
    /// The scope prefix for attribute resolution.
    /// </summary>
    public string ScopePrefix { get; }

    /// <summary>
    /// Initializes a new instance of the SandboxAttributeAccessor.
    /// </summary>
    /// <param name="ctx">The sandbox instance context.</param>
    /// <param name="prefix">The scope prefix for attribute names.</param>
    public SandboxAttributeAccessor(SandboxInstanceContext ctx, string prefix)
    {
        _ctx = ctx;
        ScopePrefix = prefix;
    }

    /// <summary>
    /// Resolves a key to its fully qualified name within the current scope.
    /// </summary>
    /// <param name="key">The attribute key.</param>
    /// <returns>The fully qualified attribute name.</returns>
    public string Resolve(string key) =>
        ScopePrefix.Length == 0 ? key : ScopePrefix + "." + key;

    /// <summary>
    /// Gets or sets an attribute value by key.
    /// </summary>
    /// <param name="key">The attribute key.</param>
    /// <returns>The attribute value, or null if not found.</returns>
    public object? this[string key]
    {
        get => _ctx.GetAttribute(Resolve(key)).GetAwaiter().GetResult();
        set => _ctx.SetAttribute(Resolve(key), value?.ToString() ?? string.Empty);
    }

    /// <summary>
    /// Gets an attribute value asynchronously.
    /// </summary>
    /// <param name="key">The attribute key.</param>
    /// <returns>The attribute value, or null if not found.</returns>
    public Task<object?> GetAsync(string key) => _ctx.GetAttribute(Resolve(key));

    /// <summary>
    /// Sets an attribute value asynchronously.
    /// </summary>
    /// <param name="key">The attribute key.</param>
    /// <param name="value">The value to set, or null.</param>
    /// <returns>A task representing the operation.</returns>
    public Task SetAsync(string key, object? value)
    {
        _ctx.SetAttribute(Resolve(key), value?.ToString() ?? string.Empty);
        return Task.CompletedTask;
    }

    // Batch-write/wait helpers. These mirror the runtime AttributeAccessor
    // (SiteRuntime/Scripts/ScopeAccessors.cs) and the deploy-gate
    // ScriptCompileSurface member-for-member so instance scripts using them COMPILE
    // in the editor and pass Test Run analysis — previously the
    // sandbox omitted them and the editor false-flagged valid scripts with CS1061.
    // Execution needs the site's DCL batch path + event-driven attribute waiter,
    // for which the central Test Run sandbox has no transport, so each throws a
    // clearly-labelled ScriptSandboxException; the same code validates/deploys/runs
    // unchanged at a site.

    /// <summary>
    /// Sandbox stand-in for <c>AttributeAccessor.WriteBatchAndWaitAsync</c>: present
    /// for editor/compile parity, throws <see cref="ScriptSandboxException"/> when run
    /// in Test Run (no device batch-write transport here).
    /// </summary>
    /// <param name="values">The attribute values to write as a batch.</param>
    /// <param name="flagKey">The flag attribute key to set to signal completion.</param>
    /// <param name="flagValue">The value to set on the flag attribute.</param>
    /// <param name="responseKey">The attribute key to observe for the device's response.</param>
    /// <param name="responseValue">The response value to wait for.</param>
    /// <param name="timeout">The maximum time to wait for the response.</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<bool> WriteBatchAndWaitAsync(
        IReadOnlyDictionary<string, object?> values, string flagKey, object? flagValue,
        string responseKey, object? responseValue, TimeSpan timeout)
        => throw NotInSandbox(nameof(WriteBatchAndWaitAsync));

    /// <summary>
    /// Sandbox stand-in for the reset-aware <c>AttributeAccessor.WriteBatchAndWaitAsync</c>
    /// overload (Gitea #36): present for editor/compile parity, throws
    /// <see cref="ScriptSandboxException"/> when run in Test Run (no device batch-write transport).
    /// </summary>
    /// <param name="values">The attribute values to write as a batch.</param>
    /// <param name="flagKey">The flag attribute key to set to signal completion.</param>
    /// <param name="flagValue">The value to set on the flag attribute.</param>
    /// <param name="responseKey">The attribute key to observe for the device's response.</param>
    /// <param name="responseValue">The response value to wait for.</param>
    /// <param name="timeout">The maximum time to wait for the response.</param>
    /// <param name="resetKey">The attribute written first and waited on before the batch.</param>
    /// <param name="resetValue">
    /// The reset value the device must echo before the batch is written. MUST NOT be null — the
    /// real accessor throws <see cref="System.ArgumentException"/>, because a null would write an
    /// empty string and then wait on "any change", reinstating the race the overload closes.
    /// </param>
    /// <param name="resetTimeout">The maximum time to wait for the reset echo; <c>null</c> means <paramref name="timeout"/>.</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<HandshakeResult> WriteBatchAndWaitAsync(
        IReadOnlyDictionary<string, object?> values, string flagKey, object? flagValue,
        string responseKey, object? responseValue, TimeSpan timeout,
        string resetKey, object? resetValue, TimeSpan? resetTimeout = null)
        => throw NotInSandbox(nameof(WriteBatchAndWaitAsync));

    /// <summary>
    /// Value-equality attribute wait — routed to the bound deployed instance cross-site
    /// (the same real event-driven waiter a site uses). Needs a bound instance; throws
    /// <see cref="ScriptSandboxException"/> when the Test Run has no instance bound.
    /// </summary>
    /// <param name="key">The attribute key to observe.</param>
    /// <param name="targetValue">The value to wait for (codec-normalized), or null for "any change".</param>
    /// <param name="timeout">The maximum time to wait.</param>
    /// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
    /// <returns>True when the attribute reached the target within the timeout; false on timeout.</returns>
    public async Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false)
        => (await _ctx.WaitForAttribute(
            Resolve(key), AttributeValueCodec.Encode(targetValue), timeout, requireGoodQuality)).Matched;

    /// <summary>
    /// Predicate-form attribute wait. Unsupported in Test Run because a script-side
    /// predicate (an in-process lambda) cannot be evaluated on the remote site — only the
    /// value-equality overloads route. Throws a clearly-labelled <see cref="ScriptSandboxException"/>.
    /// </summary>
    /// <param name="key">The attribute key to observe.</param>
    /// <param name="predicate">The predicate the attribute value must satisfy.</param>
    /// <param name="timeout">The maximum time to wait.</param>
    /// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<bool> WaitAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false)
        => throw PredicateWaitNotRoutable(nameof(WaitAsync));

    /// <summary>
    /// Value-equality attribute wait returning the full <see cref="WaitResult"/> — routed
    /// to the bound deployed instance cross-site. Needs a bound instance; throws
    /// <see cref="ScriptSandboxException"/> when the Test Run has no instance bound.
    /// </summary>
    /// <param name="key">The attribute key to observe.</param>
    /// <param name="targetValue">The value to wait for (codec-normalized), or null for "any change".</param>
    /// <param name="timeout">The maximum time to wait.</param>
    /// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
    /// <returns>The wait outcome (matched flag, matched value, quality, timed-out flag).</returns>
    public Task<WaitResult> WaitForAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false)
        => _ctx.WaitForAttribute(Resolve(key), AttributeValueCodec.Encode(targetValue), timeout, requireGoodQuality);

    /// <summary>
    /// Predicate-form attribute wait returning the full <see cref="WaitResult"/>.
    /// Unsupported in Test Run for the same reason as the predicate <see cref="WaitAsync(string, Func{object?, bool}, TimeSpan, bool)"/>
    /// overload — an in-process predicate cannot be routed to the remote site.
    /// </summary>
    /// <param name="key">The attribute key to observe.</param>
    /// <param name="predicate">The predicate the attribute value must satisfy.</param>
    /// <param name="timeout">The maximum time to wait.</param>
    /// <param name="requireGoodQuality">Whether the attribute must also have good quality to satisfy the wait.</param>
    /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/> in the sandbox.</returns>
    public Task<WaitResult> WaitForAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false)
        => throw PredicateWaitNotRoutable(nameof(WaitForAsync));

    private static ScriptSandboxException NotInSandbox(string member) =>
        new($"{member}(...) drives live device tags and the site's event-driven " +
            "attribute waiter, which aren't available in the central Test Run sandbox — " +
            "deploy to a site to exercise batch-write/wait handshakes.");

    private static ScriptSandboxException PredicateWaitNotRoutable(string member) =>
        new($"{member}(...) with a predicate can't run in Test Run — a script-side " +
            "predicate is an in-process lambda that cannot be evaluated on the remote " +
            "site. Use the value-equality overload (which routes to the bound instance), " +
            "or deploy to a site to exercise predicate waits.");
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.CompositionAccessor</c> —
/// a view of one composition: its attributes plus an invokable <c>CallScript</c>.
/// </summary>
public class SandboxCompositionAccessor
{
    private readonly SandboxInstanceContext _ctx;

    /// <summary>
    /// The path to the composition within the instance hierarchy.
    /// </summary>
    public string Path { get; }

    /// <summary>
    /// Accessor for attributes within the composition.
    /// </summary>
    public SandboxAttributeAccessor Attributes { get; }

    /// <summary>
    /// Initializes a new instance of the SandboxCompositionAccessor.
    /// </summary>
    /// <param name="ctx">The sandbox instance context.</param>
    /// <param name="path">The path to the composition within the instance hierarchy.</param>
    public SandboxCompositionAccessor(SandboxInstanceContext ctx, string path)
    {
        _ctx = ctx;
        Path = path;
        Attributes = new SandboxAttributeAccessor(ctx, path);
    }

    /// <summary>
    /// Resolves a script name to its fully qualified name within the composition.
    /// </summary>
    /// <param name="scriptName">The script name.</param>
    /// <returns>The fully qualified script name.</returns>
    public string ResolveScript(string scriptName) =>
        Path.Length == 0 ? scriptName : Path + "." + scriptName;

    /// <summary>
    /// Calls a script within the composition.
    /// </summary>
    /// <param name="scriptName">The name of the script.</param>
    /// <param name="parameters">Script parameters, or null if none.</param>
    /// <returns>The script result, or null if none.</returns>
    public Task<object?> CallScript(string scriptName, object? parameters = null)
        => _ctx.CallScript(ResolveScript(scriptName), parameters);
}

/// <summary>
/// Sandbox mirror of <c>ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts.ChildrenAccessor</c> —
/// dictionary-style access to child compositions.
/// </summary>
public class SandboxChildrenAccessor
{
    private readonly SandboxInstanceContext _ctx;
    private readonly string _selfPath;

    /// <summary>
    /// Initializes a new instance of the SandboxChildrenAccessor.
    /// </summary>
    /// <param name="ctx">The sandbox instance context.</param>
    /// <param name="selfPath">The path to the parent composition.</param>
    public SandboxChildrenAccessor(SandboxInstanceContext ctx, string selfPath)
    {
        _ctx = ctx;
        _selfPath = selfPath;
    }

    /// <summary>
    /// Gets a child composition by name.
    /// </summary>
    /// <param name="compositionName">The name of the child composition.</param>
    /// <returns>An accessor for the child composition.</returns>
    public SandboxCompositionAccessor this[string compositionName]
    {
        get
        {
            var path = _selfPath.Length == 0
                ? compositionName
                : _selfPath + "." + compositionName;
            return new SandboxCompositionAccessor(_ctx, path);
        }
    }
}

/// <summary>
/// Distinct exception so the Test Run pipeline can label sandbox-only
/// limitations differently from genuine runtime errors in user code.
/// </summary>
public class ScriptSandboxException : Exception
{
    /// <summary>
    /// Initializes a new instance of the ScriptSandboxException.
    /// </summary>
    /// <param name="message">The exception message.</param>
    public ScriptSandboxException(string message) : base(message) { }
}