ScadaBridge/docs/plans/2026-06-16-multivalue-attribute-design.md

Structured Multi-Value Attribute — Design

Date: 2026-06-16 Status: Implemented (MV-1 … MV-15, branch feature/multivalue-attribute) — full solution builds clean; feature-targeted tests green across Commons, TemplateEngine, SiteRuntime, DataConnectionLayer, Communication, Transport, ManagementService, CLI, and CentralUI. Branch: feature/multivalue-attribute

Problem

ScadaBridge's DataType enum (Boolean·Int32·Float·Double·String·DateTime·Binary) has no collection type. An attribute is persisted as a single string? Value plus a DataType discriminator. So a Galaxy/object attribute that is conceptually a list of values — e.g. MoveInWorkOrderNumbers, MoveInPartNumbers (string arrays arriving via the IpsenMESMoveIn inbound-API method) — can only be stored by collapsing it to a single DataType.String blob. We want these stored as a first-class structured multi-value attribute that round-trips through every path.

Scope (decided)

• Element types: a homogeneous list of any existing scalar DataType — String, Int32, Float, Double, Boolean, DateTime. Excluded: Binary elements and nested lists (no lists-of-lists, no lists-of-objects).
• Lifecycle paths — all four in scope:
  1. Script writes the attribute at runtime and reads it back (the IpsenMESMoveIn case); persists as a static attribute (site SQLite, survives failover).
  2. Statically authored default in a template, optionally overridden per instance, via Central UI and CLI.
  3. Read in from an OPC UA array node (DCL subscription → live attribute value).
  4. Written out to an OPC UA array node via the DCL write path.

Decision summary (defaults locked in)

Decision	Choice
Type modeling	One DataType.List member + nullable ElementDataType companion
Value encoding	JSON array, invariant culture (round-trippable)
Display encoding	ValueFormatter.FormatDisplayValue stays comma-joined, display-only
Element types	6 scalars; no Binary, no nesting
Override granularity	Whole-list replacement (no per-element override)
Element type mutability	Fixed by base attribute; not overridable on derived/instance
Bad OPC UA element	Coerce/validate; mismatch → Bad quality + log (non-fatal)
Empty vs unset	null = unset/cleared; "[]" = explicit empty list
gRPC wire	Existing string value field carries the canonical JSON (additive)

Architecture

The key insight from the blast-radius survey: most of the runtime is already collection-capable. ScriptParameters already converts to typed List<T>/T[]; the OPC UA write path wraps values in a Variant (which supports arrays natively); AttributeValueChanged already carries object?. The real work concentrates in (a) the type model, (b) a canonical encode/decode codec, (c) the InstanceActor / script-accessor boundary, (d) validation, and (e) the UI/CLI editors.

1. Type model

• Add one enum member: DataType.List (Commons/Types/Enums/DataType.cs).
• Add nullable ElementDataType (DataType?) to:
  • Commons/Entities/Templates/TemplateAttribute.cs
  • Commons/Entities/Instances/InstanceAttributeOverride.cs
  • Commons/Types/Flattening/FlattenedConfiguration.cs → ResolvedAttribute
• Invariant: ElementDataType required when DataType == List, null otherwise; element type must be one of the 6 allowed scalars.

2. Canonical value codec — new AttributeValueCodec

One round-trippable codec used everywhere a value is stored or transmitted:

• Encode(object? value):
  • scalar → invariant-culture string (identical to today's behavior; existing scalars unchanged)
  • non-string IEnumerable → JSON array, invariant culture (["WO-1","WO-2"], [1,2,3], ["2026-06-16T00:00:00Z"])
• Decode(string? value, DataType dataType, DataType? elementType):
  • List → typed List<T> (reuse the existing ScriptParameters element-conversion machinery where practical)
  • scalar → string (unchanged)
• null value = unset/cleared; "[]" = explicit empty list.

ValueFormatter.FormatDisplayValue (comma-joined) remains display-only — diff text, log lines, KPI strings — and is not the persisted/wire form.

3. Persistence & migration

• One EF Core migration, written idempotent (per the open follow-up #70 lesson — guard inserts/alters so re-running against a partially-migrated DB is safe):
  • add ElementDataType nvarchar(50) NULL to TemplateAttributes and InstanceAttributeOverrides
  • widen Value / OverrideValue from nvarchar(4000) → nvarchar(max) (lists can exceed 4000)
• Site SQLite static-attribute store: no schema change (already a string column) — it simply stores the canonical JSON.
• EF config: TemplateConfiguration.cs, InstanceConfiguration.cs map the new column (HasConversion<string>().HasMaxLength(50) for ElementDataType).

4. Flatten / resolve

• TemplateEngine/Flattening/FlatteningService.cs carries ElementDataType into ResolvedAttribute next to DataType.
• Inheritance / compose / override shape unchanged.
• Override replaces the whole list (no per-element merge).
• A derived template or instance override cannot change ElementDataType — it is fixed by the base attribute, enforced like the existing LockedInDerived path.

5. Site runtime (the core change)

• SiteRuntime/Scripts/ScopeAccessors.cs:56,73 — AttributeAccessor set / SetAsync: replace value?.ToString() with AttributeValueCodec.Encode(value). (Today a List<string> would .ToString() to "System.Collections.Generic.List1[...]"` — the central bug this fixes.) Scalars produce the same string as before.
• SiteRuntime/Actors/InstanceActor.cs:116-121 — on load, for List attributes Decode the JSON Value into a typed List<T> and store that in _attributes (scalars unchanged).
• HandleSetStaticAttribute — for List attributes: decode the canonical string → typed list for _attributes, validate element types, persist the canonical JSON to SQLite, stream the canonical JSON.
• HandleGetAttribute — unchanged; returns the live _attributes object, now a real List<T> for list attributes. Scripts read a first-class list.

6. Data Connection Layer (OPC UA read + write)

• Read: an OPC UA array node yields a CLR array → attribute value object. Coerce / validate element type against ElementDataType; on mismatch → Bad quality + log, never crash the actor.
• Write: DataConnectionLayer/Adapters/RealOpcUaClient.cs:619-628 already wraps values in new Variant(value), which supports arrays natively; a List<T>/T[] writes as an OPC UA array. Minimal change beyond passing the typed list through.

7. Validation (pre-deploy semantic)

TemplateEngine/Validation/SemanticValidator.cs + ValidationService.cs:

• ElementDataType present and a valid scalar when DataType == List; absent otherwise.
• Authored default Value (if present) must parse as a JSON array whose elements match ElementDataType.
• List attributes rejected as operands in numeric alarm triggers (HiLo / RangeViolation) and binary triggers — extends the existing NumericDataTypes guard.

8. Streaming / DebugView

• Communication/Actors/StreamRelayActor.cs:48 — encode via AttributeValueCodec (JSON for lists) instead of FormatDisplayValue. Additive: lists are a new type, so no existing wire consumer breaks; the proto string value field (sitestream.proto:57) is unchanged.
• Central DebugView renders the canonical string; for lists it shows the JSON array. Optional polish: chip rendering of list elements.

9. Central UI

• CentralUI/Components/Pages/Design/TemplateEdit.razor — attribute form: when type = List, reveal an ElementDataType dropdown and a list editor (repeatable add/remove rows) bound to the JSON value; inline per-element validation.
• CentralUI/Components/Pages/Deployment/InstanceConfigure.razor — override panel: the same list editor for overriding a list attribute.

10. CLI

• CLI/Commands/TemplateCommands.cs (and the instance-override command): add --element-type <Scalar>; --value accepts a JSON array ('["a","b"]'). Optional ergonomic alternative: repeatable --value. Validate element type before submit.
• ManagementService/ManagementActor.cs add/update attribute handlers: parse + validate ElementDataType, validate Value against it before persisting.

11. Transport (import/export)

• Transport/Serialization/EntityDtos.cs TemplateAttributeDto already carries the DataType enum + string? Value; add ElementDataType. Enum/value round-trip is otherwise automatic. BundleImporter carries the new field through.

Error handling

• Malformed JSON in a persisted Value: caught at deploy-time validation; if it ever reaches runtime decode, log + treat the attribute as Bad quality — never crash the Instance Actor (audit/best-effort principle).
• OPC UA element-type mismatch on read: Bad quality + log (non-fatal).
• Script writes a non-list to a list attribute (or vice versa): rejected at HandleSetStaticAttribute validation, surfaced to the script as an error.

Testing strategy

• Codec round-trip: every element type; empty list; embedded commas/quotes/escaping; DateTime; culture-invariance.
• Flatten: override replaces whole list; element-type lock enforced.
• Validation: good/bad authored defaults; trigger-operand rejection; missing/extra ElementDataType.
• InstanceActor: set/get typed list; SQLite persistence survives simulated failover.
• DCL: OPC UA array read coercion; Bad quality on element mismatch; Variant array write.
• Streaming: StreamRelayActor emits canonical JSON for a list attribute.
• CLI: --element-type + JSON --value parse/validate.
• UI: list-editor component behavior (if harness present).

Out of scope (deferred)

• Nested objects / lists-of-records; heterogeneous lists.
• Binary element lists.
• Per-element overrides; element-level alarm triggers.

Blast-radius reference (file:area)

Area	Key locations	Change size
Enum + entities	DataType.cs, TemplateAttribute.cs, InstanceAttributeOverride.cs, FlattenedConfiguration.cs	small
Codec (new)	Commons/Types/AttributeValueCodec.cs (new)	small–med
EF + migration	TemplateConfiguration.cs, InstanceConfiguration.cs, new migration	small
Flatten	FlatteningService.cs:177	small
Runtime boundary	ScopeAccessors.cs:56,73, InstanceActor.cs:116-121,246-315	med (core)
DCL	RealOpcUaClient.cs read coercion (write already array-capable)	small–med
Validation	SemanticValidator.cs:18-21,130-193, ValidationService.cs	small–med
Streaming	StreamRelayActor.cs:48	small
UI	TemplateEdit.razor, InstanceConfigure.razor	med (largest)
CLI + mgmt	TemplateCommands.cs, ManagementActor.cs:1441-1461	small–med
Transport	EntityDtos.cs:77-83, BundleImporter.cs:2302	small

Note: the Inbound API type system (ParameterDefinition with Object/List, InboundApiSchema) is genuinely separate from attribute DataType and is not modified; its ScriptParameters.ConvertToList/ConvertToArray conversion helpers are reusable by the codec.