scadalink-design/docs/plans/2026-05-12-script-scope-access-design.md

Script scope access: self / child / parent

Goal

Template scripts get an ergonomic read/write API for:

• The current template's attributes (Attributes["X"]).
• Child composition attributes (Children["TempSensor"].Attributes["Temperature"]).
• Child composition scripts (Children["TempSensor"].CallScript("Sample")).
• The parent composition (when this template is composed inside another): Parent.Attributes["SpeedRPM"], Parent.CallScript("Trip").

Editor (Monaco) provides completion, hover, and diagnostics on all the above.

What already exists

• Each Template has Attributes, Compositions (named sub-template references), Scripts, Alarms.
• Flattening produces ResolvedAttribute.CanonicalName as the path-qualified name: direct attrs are bare, composed attrs are "InstanceName.MemberName".
• InstanceActor stores _attributes[canonicalName] — flat dict keyed by the fully composed canonical name.
• ScriptRuntimeContext.GetAttribute(name) does a flat lookup. So GetAttribute("TempSensor.Temperature") already works if the canonical name is in the dict. What's missing is scope-relative access — a script on TempSensor cannot say "my Temperature" without knowing it's composed under some parent path.
• ScriptRuntimeContext.CallScript(name) Ask-pattern-routes to a Script Actor. Cross-composition / parent routing is not implemented.
• The actor topology is one Instance Actor per top-level instance — composed sub-templates are flattened into the parent's actor state, not separate actors. This is good news: parent/child access is path arithmetic, not ActorRef hopping.

Runtime API (new)

Three accessors layered on ScriptGlobals (in addition to the existing Instance.*, Parameters, Scripts.CallShared, etc.):

Attributes["X"]                  // read; throws if missing
Attributes["X"] = value          // write
Attributes.TryGet<T>("X", out v) // typed read with fallback
Children["TempSensor"].Attributes["Temperature"]
Children["TempSensor"].CallScript("Sample", new { count = 3 })
Parent.Attributes["SpeedRPM"]    // null check: Parent is null at the root
Parent.CallScript("Trip")

Internally each is a thin wrapper holding a ScopePath (string) plus a reference to ScriptRuntimeContext. The indexer / CallScript prepend the scope path to the key and delegate to the existing Instance.GetAttribute / Instance.SetAttribute / Instance.CallScript. No new actor messages, no new lookup pathway.

Children["X"] returns a new accessor with prefix SelfPath + "." + X. Parent returns an accessor with the parent prefix (null if no parent). Chained child/parent navigation works naturally because each accessor is the same type returning the same type.

Compile-time scope injection

Every compiled script needs to know its own ScopePath. That's captured by the flattening pipeline and passed into ScriptGlobals at execution time:

public record ScriptScope(
    string SelfPath,            // "" for root, "TempSensor" for composed
    string? ParentPath,         // null if SelfPath == ""
    IReadOnlyList<string> ChildInstanceNames);

ResolvedScript gains a Scope: ScriptScope field. The flattening service already walks the composition tree to compute canonical names — extending it to emit the scope per script is mechanical.

ScriptCompilationService.Compile reads the scope and seeds ScriptGlobals. Attributes, Children, Parent before the script runs. No code-generation; the accessors close over the scope path at construction time.

Editor surface

The editor side carries the same metadata that the runtime gets:

• The current template's attribute set (names + types).
• Each composition: instance name → resolved child template's attribute set AND script list. The form already loads compositions in TemplateEdit.
• The parent template's attribute and script lists, ONLY when the open template is composed inside another. We surface this as null otherwise.

New completion contexts:

In code	Suggests
Attributes["X"]	declared attribute names of current template
Children["X"]	composition instance names
Children["X"].Attributes["Y"]	attribute names of the resolved child template
Children["X"].CallScript("Y"	script names of the resolved child template
Parent.Attributes["X"]	parent template's attribute names
Parent.CallScript("X"	parent template's script names

New diagnostics:

• SCADA006: unknown attribute name on the appropriate scope.
• SCADA007: unknown child composition name in Children["X"].

Existing Instance.GetAttribute("X") / Instance.CallScript("X") keep working unchanged. Editor support for those can fall out of the same metadata if we want it.

Hover + signature help

• Hover Attributes["X"] → attribute X: <Type> on <TemplateName>.
• Hover Children["X"] → composition X: <ChildTemplateName>.
• Signature help for Children["X"].CallScript(...) reuses the existing shape pipeline once the child template's scripts are reachable as ScriptShape[].

What needs to be passed from the form

TemplateEdit already loads the open template's attributes and scripts. Two new pieces:

1. Resolved child compositions: for each Composition row, fetch the composed template's Attributes and Scripts. The repository already has GetTemplateByIdAsync — call it for each composition.
2. Parent template (if any): query the repository for templates that compose this one. If exactly one, pass its shape. If multiple or none, pass null and emit Parent.X accesses as diagnostics-by-the-user (since the parent context is ambiguous in design time — the runtime knows because it's running inside one specific deployment, but the editor doesn't).

Edge case: a template composed into multiple parents has no single parent at edit time. Acceptable behaviour: Parent autocompletion is suppressed; using it still compiles but emits a warning at deploy time. Document this clearly.

Phased rollout

1. Runtime first. Add Attributes / Children / Parent accessors. Wire scope into ResolvedScript and the flattening pipeline. Test with existing flat templates (Scope.SelfPath = ""). Verify a composed script's Attributes["Temperature"] reads through correctly. Site-runtime tests.

2. Flattening + deployment. Verify the deployed artifact carries the new Scope field through ResolvedScript → FlattenedScript → site-side. Run a round-trip deploy + execute.

3. Editor metadata. TemplateEdit fetches child template shapes for each composition and optionally the parent. New Monaco context fields.

4. Editor completion + diagnostics. New string-literal completion contexts. SCADA006 / SCADA007 diagnostics on the Diagnose path. Hover.

Each phase is a separate commit and independently shippable.

Out of scope

• Composing the same template multiple times under different names on the same parent (already supported by the data model; the editor just lists each composition).
• Sibling-of-sibling access (Children["A"].Parent.Children["B"]). The accessor API supports it naturally but we don't actively suggest it.
• Locking-aware writes (Attributes["X"] = v when X is locked). The attribute lock is enforced at deployment validation, not at script-write time; runtime writes that hit a locked attribute should reject. Out of scope for this design — covered by the existing lock-enforcement pass.
• A formal type for Children / Parent in the editor's Roslyn analysis (the strict Roslyn route would auto-generate per-template accessor types). We use a dictionary-style indexer for both runtime and editor, with editor awareness coming from the metadata pipeline, not from per-template C# types.

Open questions

• Should Attributes["X"] throw or return null on unknown key? The existing GetAttribute logs a warning and returns null. Same here for consistency.
• Async vs sync indexer? Decided: both. Sync Attributes["X"] / Attributes["X"] = v indexer for ergonomics, plus Attributes.GetAsync("X") / Attributes.SetAsync("X", v) for callers that want to be explicit about the actor Ask. The sync path internally blocks on .GetAwaiter().GetResult() — acceptable because all script bodies already run on a dedicated blocking-I/O dispatcher per the project conventions in CLAUDE.md.