@memoarchitect/ontology 0.6.5 → 0.8.22

package/src/architecture/implementation/ui/memo_ui.sysml

@@ -5,31 +5,92 @@
 // UI is an implementation concern (rendered UI is software; physical controls
 // are hardware), so it lives in the implementation layer, not operational.
 package memo_architecture_implementation_ui {
+    private import Metaobjects::SemanticMetadata;
     private import ScalarValues::*;
 
     private import memo_core_common::*;
     private import memo_core_enumerations::*;
+    private import memo_assurance_safety_risk::*;   // RiskControlMeasure
     private import memo_core_relationships::*;
     private import memo_architecture_operational_activities::*;
     private import memo_architecture_operational_scenarios::*;
     private import memo_architecture_operational_use_cases::*;
     private import memo_architecture_functional_functions::*;
+    private import memo_architecture_implementation_software_structure::*;
+    private import memo_architecture_implementation_hardware_common::*;
     private import memo_assurance_human_factors::*;
 
+    // Every concrete UI form, holding and held alike. A screen is not a
+    // different KIND of thing from a button — it is a UIElement that happens to
+    // contain others, exactly as an assembly is a part that contains parts.
+    // The forms below are classifications, not classes, so one tree carries the
+    // whole interface.
     enum def UIElementFormKind {
+        // ── forms that hold other elements ──
+        enum screen;
+        enum dialog;
+        enum panel;
+        enum menu;
+        enum tab;
+        enum drawer;
+        enum wizardStep;
+        // ── controls the user acts on ──
+        // Rendered controls only. A knob, toggle, lamp, or buzzer the user
+        // touches is not software: it is an OperatorInterfaceElement below.
         enum button;
         enum field;
         enum selector;
-        enum knob;
-        enum switchControl;
         enum slider;
+        // ── forms that present information ──
         enum table;
         enum chart;
         enum icon;
-        enum indicatorLamp;
-        enum audibleIndicator;
-        enum hapticIndicator;
         enum textMessage;
+        // ── chrome ──
+        // Non-functional: a rule, a background, a brand mark. Declared, never
+        // merely implied — CR-MED-110 exempts `decoration` from needing a
+        // design record, so an element left unclassified fails rather than
+        // slipping through as scenery.
+        enum decoration;
+    }
+
+    // ─── Screen geometry ─────────────────────────────────────────
+    // Position and size of a UIElement inside its PARENT element, each value
+    // normalized to 0..1 of the parent's box — not pixels. Two consequences
+    // are wanted: an element survives a re-capture at a different resolution
+    // or device scale, and a child's box is stated against its parent, which
+    // is exactly what the containment tree already asserts. Absolute pixels
+    // stay recoverable from the ScreenCapture's pixelWidth / pixelHeight.
+    attribute def RegionBounds {
+        attribute x : Real;
+        attribute y : Real;
+        attribute width : Real;
+        attribute height : Real;
+    }
+
+    // How an element appears relative to its parent and siblings. It records
+    // design intent a bare rectangle cannot: an element whose box escapes its
+    // parent and covers its siblings is a defect if it is `inline` and correct
+    // if it is `overlay`, and the geometry alone does not say which. A
+    // renderer reads it to decide what to clip and what to draw on top; a
+    // reviewer reads it to know whether an overlap is intended.
+    enum def UIDisclosureKind {
+        enum inline;       // laid out inside the parent, sharing space with siblings
+        enum overlay;      // dropdown, popover, modal — drawn OVER parent and siblings
+        enum transient;    // tooltip, toast — appears over everything, then withdraws
+        enum scrolled;     // inside the parent, but beyond its viewport until scrolled
+        enum conditional;  // rendered only while a stated condition holds
+    }
+
+    // How the element's bounds were obtained. Automatic boundary detection
+    // PROPOSES; a reviewer DISPOSES. In a regulated review the reader must be
+    // able to see which boxes a human confirmed and which the tool guessed, so
+    // that provenance is model content and not a workbench-only flag.
+    enum def BoundsDetectionKind {
+        enum manual;
+        enum automatic;
+        enum automaticConfirmed;
+        enum imported;
     }
 
     // The interaction intents a step or action can carry (§18).
@@ -54,20 +115,73 @@ package memo_architecture_implementation_ui {
         attribute uiTechnology : String;
     }
 
-    part def UIContainer specializes ArchitectureElement {
-        attribute containerKind : String;
-        attribute navigationRole : String;
+    // What a rendered control and a physical one genuinely share: a label, an
+    // accessibility story, and — when they annunciate — an alarm character.
+    // The base exists so that the §18 traceability relations can type against
+    // "something the user interacts with" rather than against software
+    // specifically. Without it a use error on a knob would be unmodellable,
+    // because ErrorAtElement would only accept a UIElement.
+    abstract part def InteractionElement specializes ArchitectureElement {
+        attribute labelText : String;
+        attribute accessibilitySummary : String;
+        // alarm annunciation (optional; IEC 60601-1-8)
+        attribute alarmPriority : NotificationPriorityKind[0..1];
+        attribute annunciationModality : String;
+        attribute silenceable : Boolean;
     }
 
-    // One UIElement. The widget form — screen (field/table/chart) or physical
-    // (knob/switch/indicatorLamp/haptic) — is the `formKind` enum, not a
-    // subclass. Input/output/navigation/alarm/display/physical-control
-    // descriptors are optional attributes; a physical control's mechanical
-    // realization is a hardware part linked by ControlImplementedBy.
-    part def UIElement specializes ArchitectureElement {
+
+    // One UIElement — the single UI part type. The widget form — holding
+    // (screen/panel/dialog), acting (button/knob/slider), presenting
+    // (field/table/chart), physical (knob/switch/indicatorLamp/haptic), or
+    // decorative — is the `formKind` enum, not a subclass.
+    // Input/output/navigation/alarm/display/physical-control descriptors are
+    // optional attributes; a physical control's mechanical realization is a
+    // hardware part linked by ControlImplementedBy.
+    //
+    // Composition is the ordinary `Composes` relation, so a screen's element
+    // tree is an ordinary part tree: CR-ONT-001 already forbids cycles in it,
+    // impact analysis already walks it, and requirements, functions, use
+    // errors, and risk controls already trace to it. Screen layout adds four
+    // numbers to that tree — it does not add a tree.
+    //
+    // A UIElement IS a structural SOFTWARE ITEM (IEC 62304 §3.25) and
+    // specializes SoftwareElement, inheriting safetyClass and complexity, so the
+    // interface is classified and decomposed like the software it is.
+    //
+    // It specializes SoftwareElement and NOT SoftwareModule: the module view is
+    // CODE, and a screen is not a source module. Runtime processes are
+    // SoftwareComponent, code is SoftwareModule, and the UI is a third view of
+    // the same software — a sibling of those, not a kind of either.
+    part def UIElement specializes SoftwareElement, InteractionElement {
         attribute formKind : UIElementFormKind;
-        attribute labelText : String;
-        attribute accessibilitySummary : String;
+        // ── screen layout (optional; set for elements that are laid out) ──
+        // Bounds are relative to the parent element in the Composes tree; a
+        // root screen's bounds are the full frame.
+        attribute bounds : RegionBounds[0..1];
+        attribute disclosureKind : UIDisclosureKind[0..1];
+        // The condition under which the element renders; meaningful when
+        // disclosureKind is `conditional`.
+        attribute visibilityCondition : String;
+        // Boundary colour as a CSS colour token. Presentation, but modelled: a
+        // review print, an exported figure, and the workbench must agree on
+        // which box is which, and a colour assigned only in a tool session does
+        // not survive the export.
+        attribute boundaryColor : String;
+        // Capture-relative fill transparency for region review overlays. A
+        // modelled value keeps interactive review and exported figures aligned.
+        attribute boundaryOpacity : Real[0..1];
+        // Stroke width of the same box, in pixels. Colour and opacity are
+        // modelled so a review print, an exported figure, and the workbench
+        // agree on which box is which; a width chosen per renderer breaks that
+        // agreement for exactly the same reason.
+        attribute boundaryWidth : Real[0..1];
+        attribute detectionMethod : BoundsDetectionKind[0..1];
+        attribute detectionConfidence : Real[0..1];
+        attribute confirmedBy : String;
+        attribute confirmedAt : String;
+        // ── role of a holding form (optional) ──
+        attribute navigationRole : String;
         // input descriptors (optional)
         attribute inputConstraints : String;
         attribute defaultValue : String;
@@ -75,15 +189,72 @@ package memo_architecture_implementation_ui {
         attribute updateRate : String;
         attribute unitsDisplayed : String;
         attribute informationContent : String;
-        // navigation (optional)
-        attribute navigationTarget : String;
-        // alarm annunciation (optional)
-        attribute alarmPriority : NotificationPriorityKind[0..1];
-        attribute annunciationModality : String;
-        attribute silenceable : Boolean;
-        // physical control (optional)
+    }
+
+    // ─── Physical operator interface ─────────────────────────────
+    // The hardware the user actually touches and reads. IEC 60601-1 marks
+    // "controls and instruments" and defines OPERATOR; this is that surface,
+    // covering both directions — what the operator actuates and what the
+    // device shows back — because a front panel is one interface, not two.
+    //
+    // It is a PhysicalComponent, so it inherits part number, material, and the
+    // ISO 10993-1 patient-contact characterization that a touched surface
+    // needs and that software can never have. That inheritance is the reason
+    // these forms had to leave UIElement: as UIElementFormKind members they
+    // were software items with no way to state any of it.
+    enum def OperatorInterfaceFormKind {
+        // ── actuated by the operator ──
+        enum knob;
+        enum dial;
+        enum pushButton;
+        enum toggleSwitch;
+        enum rockerSwitch;
+        enum lever;
+        enum physicalSlider;
+        enum keypad;
+        enum footPedal;
+        enum touchSurface;
+        // ── presented to the operator ──
+        enum indicatorLamp;
+        enum gauge;
+        enum audibleIndicator;
+        enum hapticIndicator;
+        enum printedMarking;
+    }
+
+    part def OperatorInterfaceElement specializes PhysicalComponent, InteractionElement {
+        attribute formKind : OperatorInterfaceFormKind;
+        // actuation (optional; set for actuated forms)
         attribute actuationForce : String;
+        attribute actuationTravel : String;
         attribute guardedAgainstInadvertentActuation : Boolean;
+        attribute tactileFeedback : String;
+        // presentation (optional; set for presented forms)
+        attribute legendText : String;
+        attribute luminanceOrVolume : String;
+    }
+
+    // ─── Captured evidence ───────────────────────────────────────
+    // One image of one screen. MemoEvidence, not ArchitectureElement: it
+    // records what a specific build actually displayed at a specific time,
+    // which is the provenance a design review or a usability engineering file
+    // needs before it can rely on the picture. The screen it depicts is an
+    // ordinary UIElement with formKind = screen.
+    part def ScreenCapture specializes MemoEvidence {
+        attribute imageUri : String;
+        // Content hash of the image bytes. The screenshot is the evidence, so
+        // it must be tamper-evident: a DHF reference to a mutable file is not
+        // a reference to anything.
+        attribute imageHash : String;
+        attribute pixelWidth : Integer;
+        attribute pixelHeight : Integer;
+        attribute captureDate : String;
+        // Which build produced this rendering. A screenshot without a build is
+        // undated design intent, not evidence of the device.
+        attribute capturedBuild : String;
+        // Device, viewport, locale, theme, user role — everything that changes
+        // what the screen shows without changing the software.
+        attribute captureContext : String;
     }
 
     // UI state is presentation state — distinct from system/device state.
@@ -103,57 +274,109 @@ package memo_architecture_implementation_ui {
     }
 
     // A reusable dialogue structure through the UI; a selected path through
-    // it is an UIScenario.
+    // it is a MemoScenario with scenarioKind `ui`.
     action def InteractionFlow specializes MemoAction {
         attribute entryPoint : String;
         attribute exitPoint : String;
     }
 
-    part def UIScenario specializes MemoScenario {
-        ref parentFlow : InteractionFlow[0..1];
-    }
-
-    connection def UITransition :> MemoRelationship {
-        attribute triggeringEvent : String;
-        attribute guardCondition : String;
-        end sourceState : UIState;
-        end targetState : UIState;
-    }
     connection def DataBinding :> MemoRelationship {
         attribute bindingExpression : String;
         attribute refreshPolicy : String;
-        end boundElement : UIElement;
-        end dataSource : MemoPart;
+        end boundElement : InteractionElement :>> source;
+        end dataSource : MemoItem :>> target;
+    }
+    abstract connection dataBindingLinks : DataBinding[*];
+    metadata def <dataBinding> DataBindingMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = dataBindingLinks meta SysML::Usage;
     }
-    connection def PresentsState :> MemoRelationship {
-        end userInterface : UserInterface;
-        end uiState : UIState;
+    // `PresentsState` had zero usages anywhere in the tree (R10-S6). Its
+    // audited native form, `exhibit state`, does not actually fit: `UIState`
+    // is a `part def` with plain string attributes, not a `state def`, and
+    // SysIDE rejects `exhibit` referencing anything that does not conform to
+    // `States::StateAction` ("An exhibit state must reference another
+    // state"). Free deletion rather than a migration — nothing referenced
+    // it, so nothing to preserve. If `UIState` is ever restructured onto a
+    // real state machine, `exhibit state` becomes available then.
+
+    // ── Screen layout relations ──────────────────────────────────
+    // Which modelled screen an image is a rendering of.
+    connection def CapturesScreen :> MemoRelationship {
+        end capture : ScreenCapture :>> source;
+        end screen : UIElement :>> target;
+    }
+    abstract connection capturesScreenLinks : CapturesScreen[*];
+    metadata def <capturesScreen> CapturesScreenMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = capturesScreenLinks meta SysML::Usage;
+    }
+
+    // Activating this element opens another screen. This is NAVIGATION, not
+    // containment — the opened screen is not laid out inside the element, so
+    // it is not a Composes child and the geometric rules do not relate them.
+    // Conflating the two was the mistake that made "clicking takes you to a
+    // child view" look like spatial nesting; it is a separate frame reached
+    // from here, and only this relation says so.
+    connection def NavigatesTo :> MemoRelationship {
+        attribute triggerGesture : String;
+        end sourceElement : UIElement :>> source;
+        end targetScreen : UIElement :>> target;
+    }
+    abstract connection navigatesToLinks : NavigatesTo[*];
+    metadata def <navigatesTo> NavigatesToMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = navigatesToLinks meta SysML::Usage;
     }
 
     // ── §18 traceability ─────────────────────────────────────────
     connection def ElementTriggersAction :> MemoRelationship {
-        end element : UIElement;
-        end triggeredAction : UIAction;
+        end element : InteractionElement :>> source;
+        end triggeredAction : UIAction :>> target;
     }
-    connection def ActionInvokesFunction :> MemoRelationship {
-        end uiAction : UIAction;
-        end systemFunction : SystemFunction;
+    abstract connection elementTriggersActionLinks : ElementTriggersAction[*];
+    metadata def <elementTriggersAction> ElementTriggersActionMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = elementTriggersActionLinks meta SysML::Usage;
     }
+    // `ActionInvokesFunction` is native `perform` (R10-S6): write
+    // `perform <systemFunction>;` inside the `UIAction` usage instead.
     connection def FlowServesUseCase :> MemoRelationship {
-        end interactionFlow : InteractionFlow;
-        end useCase : UseCase;
+        end interactionFlow : InteractionFlow :>> source;
+        end useCase : UseCase :>> target;
+    }
+    abstract connection flowServesUseCaseLinks : FlowServesUseCase[*];
+    metadata def <flowServesUseCase> FlowServesUseCaseMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = flowServesUseCaseLinks meta SysML::Usage;
     }
-    // The UI-layer scenario realizes exactly one FunctionalScenario one layer
-    // up (the interaction sequence that carries out the function sequence),
-    // completing the OperativeScenario → FunctionalScenario → UIScenario chain.
+    // A UI scenario realizes a functional scenario one layer up: each is a
+    // MemoScenario selected by scenarioKind rather than a separate definition.
     connection def ErrorAtElement :> MemoRelationship {
-        end useError : UseError;
-        end element : UIElement;
+        end useError : UseError :>> source;
+        end element : InteractionElement :>> target;
+    }
+    abstract connection errorAtElementLinks : ErrorAtElement[*];
+    metadata def <errorAtElement> ErrorAtElementMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = errorAtElementLinks meta SysML::Usage;
     }
     // A risk control implemented by a UI element or by task design
     // (confirmation dialog, lockout, guarded control).
     connection def ControlImplementedBy :> MemoRelationship {
-        end riskControl : VerifiableElement;
-        end implementingElement : ArchitectureElement;
+        end riskControl : RiskControlMeasure :>> source;
+        end implementingElement : ArchitectureElement :>> target;
+    }
+    abstract connection controlImplementedByLinks : ControlImplementedBy[*];
+    metadata def <controlImplementedBy> ControlImplementedByMetadata :> SemanticMetadata {
+        :> annotatedElement : SysML::ConnectionDefinition;
+        :> annotatedElement : SysML::ConnectionUsage;
+        :>> baseType = controlImplementedByLinks meta SysML::Usage;
     }
 }

package/src/architecture/logical/interfaces/memo_interfaces.sysml

@@ -44,12 +44,24 @@ package memo_architecture_logical_interfaces {
         attribute apiStyle : String;
     }
 
+    // Software interaction contracts specialize the native MEMO interface
+    // family. Concrete technologies add their protocol roles and message
+    // flows; ports remain the endpoints that components actually own.
+    abstract interface def SoftwareInterface specializes Interface {
+        // `default`, not `=`. A bare `=` in a definition BINDS the value, and
+        // a binding cannot be overridden by a usage — which asserted that
+        // every software interface is bidirectional and made a directional one
+        // inexpressible. A ROS topic publisher → subscriber is the obvious
+        // counterexample, and it is the common case rather than an exotic one.
+        attribute :>> direction default DirectionKind::inputOutput;
+    }
+
     // A typed thing exchanged at a boundary. Concrete items such as
     // AlarmSignal and FlowCommand specialize this type; they are neither
     // functions nor generic action-flow notation.
     // The kind of item is given by itemKind (data / command / signal / …);
     // the control-specific fields below apply only when itemKind = command.
-    item def InterfaceItem specializes MemoExchangeItem {
+    item def InterfaceItem specializes MemoItem {
         attribute itemKind : InterfaceItemKind;
         attribute confidentialityClass : String;
         attribute integrityClass : String;
@@ -67,8 +79,7 @@ package memo_architecture_logical_interfaces {
         attribute interfaceKind : InterfaceKind;
         attribute protocolSemantics : String;
     }
-    port def DataPort {
-        attribute direction : DirectionKind;
+    port def DataPort specializes MemoPort {
         attribute interfaceType : String;
     }
     port def SensorPort specializes DataPort { attribute sensorDomain : String; }
@@ -76,14 +87,45 @@ package memo_architecture_logical_interfaces {
 
     part def ComponentExchange specializes ArchitectureElement {
         attribute exchangeKind : FlowKind;
-        // Typed endpoints (CR-ONT-002). A component or a boundary port may
-        // terminate an exchange, so the ends are MemoPart-typed.
-        ref sourceEndpoint : MemoPart[0..1];
-        ref targetEndpoint : MemoPart[0..1];
-        // Descriptive port paths (e.g. "TLM.TLM_MODE_OUT") for AADL
-        // round-trips; labels only — never references.
-        attribute sourcePortPath : String;
-        attribute targetPortPath : String;
+        // Metaclass-neutral endpoints. CR-ONT-002 used to read: "Typed
+        // endpoints. A component or a boundary port may terminate an exchange,
+        // so the ends are MemoPart-typed." That reasoning was circular —
+        // PhysicalPort and SoftwarePort are part defs precisely SO THAT they
+        // could satisfy this typing, and the typing was justified by their
+        // being parts. Track A0 cut the circle at the ends, which is the side
+        // that has to move first: A1 turns those two into `port def`s, and a
+        // port cannot specialize a part-based type.
+        //
+        // The constraint the type was carrying — an endpoint is a component or
+        // a boundary port, never a requirement or a document — is now stated
+        // where it can be checked across metaclasses, as CR-ONT-072/073 in
+        // src/rules/ontology/ontology_invariants.sysml.
+        //
+        // `Base::Anything` rather than no type at all — the only place in this
+        // change that reaches for it. The 36 untyped ends in
+        // memo_core_relationships are `end` declarations, and an untyped `end`
+        // is established practice; an untyped `ref` with a multiplicity is not
+        // something MEMO's own grammar accepts (`Expecting token of type ';'
+        // but found '['`), and the grammar is not in this session's scope.
+        // `Base::Anything` is what the standard's `Allocations::Allocation`
+        // types its own ends with, so it is the conforming spelling of "any
+        // element", not a workaround.
+        ref sourceEndpoint : Base::Anything[0..1];
+        ref targetEndpoint : Base::Anything[0..1];
+        // `sourcePortPath` / `targetPortPath` are GONE. They were String
+        // "descriptive port paths (e.g. TLM.TLM_MODE_OUT) for AADL round-trips;
+        // labels only — never references", which is §13.3's string
+        // pseudo-reference: nothing can follow a string to an element, so
+        // anything built on them produced no traceability.
+        //
+        // Measured across the 92 sites in the GPCA example before removing
+        // them: 23 merely restated the endpoint the ref already named (15 gave
+        // the port's own display name, 8 were prose like "HW-001:
+        // GPCA_HW_Sensors"), and the other 69 named a port ON the endpoint
+        // component, resolving to 49 distinct AADL features. Those 49 are
+        // declared as real ports now and the endpoint refs point straight at
+        // them, which is what Track A1 making SoftwarePort a `port def` is for.
+        // The AADL round-trip is better served by an element than by its name.
         ref allocatedExchanges : FunctionalExchange[0..*];
         attribute direction : DirectionKind;
         // Connection timing discipline from the source architecture
@@ -94,9 +136,18 @@ package memo_architecture_logical_interfaces {
     // Boundary data port of a software system (e.g. an AADL top-level
     // data port), modeled as a first-class element so exchanges can
     // reference it and views can render the system boundary.
-    part def SoftwarePort specializes InterfaceElement {
+    //
+    // A `port def` (Track A1) — see PhysicalPort in
+    // memo_architecture_realization_physical for why the specialization moved
+    // off InterfaceElement, why `direction` is native now (Track A2), and why
+    // `portKind` is duplicated on both ports instead of hoisted onto a base.
+    port def SoftwarePort specializes MemoPort {
         attribute portKind : InterfaceKind;
-        attribute direction : DirectionKind;
+        // AADL port category (plan C2). Sampled vs. queued delivery decides
+        // whether a missed deadline drops a sample or grows a queue, which the
+        // timing analysis and the safety case both need and neither could ask
+        // the model for. `portKind` says what crosses; this says how.
+        attribute portCategory : PortCategoryKind;
         attribute dataTypeName : String;
     }
 }