RuleScript v1.10.0

RuleScript v1.10.0

RuleScript v1.10.0 promotes HostTrigger runtime support to the stable release line. The release adds long-running script runtimes that can wait for host-dispatched trigger requests, exposes HostTrigger metadata through analysis/runtime symbols, and aligns runtime creation with existing file execution and debug-session flows.

HostTrigger Functions

Scripts can mark user functions as host-dispatched triggers:

@HostTrigger("LotArrived")
function OnLotArrived(lotId: string) -> void:
    Print("lot arrived: " + lotId);
    return;
endfunction

HostTrigger metadata is surfaced through RuleScriptFunctionSymbol.HostTriggerMetadata and RuleScriptAnalysisResult.HostTriggers, allowing embedding applications to discover available trigger names, signatures, parameters, documentation, and source ranges before running a script.

Long-Running Runtime

RuleScriptEngine.CreateRuntime creates a RuleScriptRuntime that can be started, triggered, and stopped by the host:

var engine = new RuleScriptEngine
{
    ExecutionTimeoutEnabled = false
};

var runtime = engine.CreateRuntime(script);
var running = runtime.StartAsync();

await runtime.TriggerAsync("LotArrived", ["LOT-001"]);
await runtime.TriggerAsync("LotArrived", ["LOT-002"]);

await runtime.StopAsync();
await running;

A script runtime must contain a trigger dispatcher:

parallel:
    trigger task:
        dispatch;
    endtask
endparallel

The dispatcher remains active after each request, so StartAsync continues running until the host calls StopAsync, cancellation is requested, or the runtime faults.

Runtime Creation From Files

RuleScriptEngine.CreateRuntimeFromFile starts from the same project-loading behavior as ExecuteFile and ExecuteFileAsync:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules",
    ExecutionTimeoutEnabled = false
};

var runtime = engine.CreateRuntimeFromFile("main");

foreach (var trigger in runtime.HostTriggers)
{
    Console.WriteLine($"{trigger.HostTriggerMetadata?.Name}: {trigger.Signature}");
}

File-based runtime creation honors WorkingDirectory, ScriptFileExtension, ImportResolver, and existing import/module loading behavior.

Debug Session Runtime Support

RuleScriptDebugSession can create runtimes from script text or files while preserving breakpoint, stepping, pause, continue, and runtime-event inspection behavior:

var engine = new RuleScriptEngine
{
    WorkingDirectory = @"C:\rules",
    ExecutionTimeoutEnabled = false
};

engine.AddBreakpoint("main.rules", 12);

var session = new RuleScriptDebugSession(engine);
var runtime = session.CreateRuntimeFromFile("main.rules");

var running = runtime.StartAsync();
var pause = await session.WaitForPauseAsync();

Console.WriteLine(pause.Kind);
Console.WriteLine(session.CurrentSnapshot?.CallStack.Count);

session.Continue();

await runtime.TriggerAsync("LotArrived", ["LOT-001"]);
await runtime.StopAsync();
await running;

Debug event handlers are installed while the runtime is executing and restored after the runtime completes.

Formatter Support

RuleScriptFormatter.Format now formats HostTrigger attributes with the attribute attached to @ and the following function declaration on its own line:

@HostTrigger("TriggerTest")
export function Test():
    Print("Something triggered");
endfunction

Spaced input such as @ HostTrigger(...) export function is normalized to the canonical attribute form.

Compatibility Notes

• Existing scripts, host functions, built-ins, imports, Execute, ExecuteAsync, ExecuteFile, and ExecuteFileAsync behavior remain compatible.
• Existing parallel, task, trigger task, and dispatch syntax is unchanged.
• HostTrigger handlers are executed by the interpreter; host threads enqueue trigger requests instead of directly invoking user functions.
• HostTrigger handlers may call built-in functions such as Print.
• Registered host-function thread-safety checks continue to apply to ordinary parallel task execution.
• StopAsync is the expected way to end a long-running HostTrigger runtime.

Validation

The v1.10.0 work is covered by tests for:

• HostTrigger lexer, parser, analysis, and runtime metadata
• runtime start, trigger dispatch, FIFO request ordering, and stop behavior
• keeping trigger dispatchers alive after handling requests
• CreateRuntimeFromFile project loading and working-directory behavior
• debug-session runtime creation from script text and files
• breakpoint pause and continue behavior in debug-created runtimes
• HostTrigger handler calls to built-in and registered host functions
• formatter normalization for @HostTrigger(...) function
• formatter normalization for @HostTrigger(...) export function
• v1.9 strongly typed function and overload regression coverage