# 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.):

```csharp
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:

```csharp
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.