Add validated OpenPLC RTO and RES lowering

Author: C-White-1

ARCHITECTURE.md

@@ -92,7 +92,8 @@ native project-directory packager, with no direct CODESYS dependency or
 emitted CODESYS metadata. The native packager currently accepts only the
 evidenced local-BOOL serial and two-path parallel Ladder subset, canonical
 Rockwell `TON` and `TOF`/`.DN` pairs, and optional `%MD` `TON` elapsed-time
-telemetry. It
+telemetry. The evidenced adjacent Rockwell `RTO`/`.DN`/`RES` group is lowered
+through a generated, target-owned `TF_RTO` compatibility function block. It
 rejects other semantics before writing a partial project. Native OpenPLC
 editor/runtime compatibility is expanded only after editor, compiler, and
 runtime evidence—not by inferring that superficially similar blocks are

docs/experiments/OpenPLC-native-project-compatibility.md

@@ -270,6 +270,40 @@ opened and compiled successfully in OpenPLC. Its runtime behavior also passed
 the immediate-on, five-second delayed-off, and cancellation checks without
 manual changes, validating the complete TwinForge generation path.
 
+### Retentive timer and reset evidence
+
+OpenPLC does not provide Rockwell's Ladder-only `RTO` and `RES` instructions
+as native IEC blocks. TwinForge therefore lowers the evidenced source group to
+a target-specific `TF_RTO` Structured Text function block. Its interface maps
+Rockwell timer members without adding target behavior to the neutral model:
+
+| Rockwell | `TF_RTO` |
+| --- | --- |
+| `.EN` | `Enabled` |
+| `.TT` | `TT` |
+| `.DN` | `Q` |
+| `.ACC` | `ET` |
+| `.PRE` | `PT` |
+| `RES(timer)` | `RESET` |
+
+The reference and independently generated projects compiled successfully.
+Runtime tests confirmed partial accumulation, retention while disabled,
+resumption from the retained value, latched completion, `Enabled` and `TT`
+state, and clearing of elapsed time and status through reset.
+
+The initial lowering deliberately requires adjacent canonical source rungs:
+
+```text
+XIC(enable)RTO(timer,?,?);
+XIC(timer.DN)OTE(output);
+XIC(reset)RES(timer);
+```
+
+Other ordering or shared-reset arrangements are rejected rather than guessed.
+The source still contains genuine Rockwell `RTO` and `RES` instructions; the
+generated `TF_RTO` block is an explicitly identified compatibility mapping,
+not a claim that OpenPLC implements those Rockwell instructions natively.
+
 The native project's PLCopen XML export should also be retained as comparison
 evidence. It can reveal semantic differences between TwinForge's generic XML
 and OpenPLC's serialization, even though it cannot currently be loaded through

docs/roadmaps/architecture-refactoring-roadmap.md

@@ -323,8 +323,11 @@ Deferred until another device profile or target exists:
   `TOF` declaration and block type
 - [x] Validate the TwinForge-generated `TOF` fixture through OpenPLC compile
   and runtime behavior tests
-- [ ] Establish the required retentive state and reset semantics before
-  implementing Rockwell `RTO`/`RES` lowering
+- [x] Establish retained accumulator, enable, timing, done, pause/resume, and
+  reset semantics for Rockwell `RTO`/`RES`
+- [x] Implement the evidenced adjacent `RTO`/`.DN`/`RES` pattern through the
+  generated OpenPLC `TF_RTO` compatibility function block
+- [x] Compile and runtime-test the TwinForge-generated `RTO/RES` fixture
 - [ ] Revisit physical channel and CIP assembly entities when EDS or live
   evidence supports them
 - [ ] Review this document whenever a module gains a second independent

examples/OpenPLC/native-rto-generated/devices/configuration.json

@@ -0,0 +1,29 @@
+{
+  "deviceBoard": "OpenPLC Runtime v3",
+  "communicationPort": "",
+  "runtimeIpAddress": "",
+  "compileOnly": true,
+  "communicationConfiguration": {
+    "modbusRTU": {
+      "rtuInterface": "Serial",
+      "rtuBaudRate": "115200",
+      "rtuSlaveId": null,
+      "rtuRS485ENPin": null
+    },
+    "modbusTCP": {
+      "tcpInterface": "Ethernet",
+      "tcpMacAddress": "DE:AD:BE:EF:DE:AD",
+      "tcpStaticHostConfiguration": {
+        "ipAddress": "",
+        "dns": "",
+        "gateway": "",
+        "subnet": ""
+      }
+    },
+    "communicationPreferences": {
+      "enabledRTU": false,
+      "enabledTCP": false,
+      "enabledDHCP": true
+    }
+  }
+}

examples/OpenPLC/native-rto-generated/devices/pin-mapping.json

@@ -0,0 +1 @@
+[]

examples/OpenPLC/native-rto-generated/pous/function-blocks/TF_RTO.st

@@ -0,0 +1,70 @@
+FUNCTION_BLOCK TF_RTO
+VAR_INPUT
+	IN : bool;
+	RESET : bool;
+	PT : time;
+END_VAR
+
+VAR_OUTPUT
+	Q : bool;
+	ET : time;
+	Enabled : bool;
+	TT : bool;
+END_VAR
+
+VAR
+	SegmentTimer : TON;
+	RetainedTime : time := T#0s;
+	RemainingTime : time := T#0s;
+	WasEnabled : bool := FALSE;
+END_VAR
+
+Enabled := IN;
+
+IF RESET THEN
+    SegmentTimer(IN := FALSE, PT := T#0s);
+    RetainedTime := T#0s;
+    RemainingTime := T#0s;
+    ET := T#0s;
+    Q := FALSE;
+    Enabled := FALSE;
+    TT := FALSE;
+    WasEnabled := FALSE;
+ELSIF IN AND NOT Q THEN
+    IF RetainedTime >= PT THEN
+        RetainedTime := PT;
+        ET := PT;
+        Q := TRUE;
+        TT := FALSE;
+        SegmentTimer(IN := FALSE, PT := T#0s);
+    ELSE
+        RemainingTime := PT - RetainedTime;
+        SegmentTimer(IN := TRUE, PT := RemainingTime);
+        ET := RetainedTime + SegmentTimer.ET;
+        IF SegmentTimer.Q THEN
+            RetainedTime := PT;
+            ET := PT;
+            Q := TRUE;
+        END_IF;
+        TT := NOT Q;
+    END_IF;
+ELSIF NOT IN THEN
+    IF WasEnabled AND NOT Q THEN
+        RetainedTime := RetainedTime + SegmentTimer.ET;
+        IF RetainedTime >= PT THEN
+            RetainedTime := PT;
+            Q := TRUE;
+        END_IF;
+    END_IF;
+    SegmentTimer(IN := FALSE, PT := T#0s);
+    ET := RetainedTime;
+    TT := FALSE;
+ELSE
+    SegmentTimer(IN := FALSE, PT := T#0s);
+    ET := RetainedTime;
+    TT := FALSE;
+END_IF;
+
+WasEnabled := IN;
+
+END_FUNCTION_BLOCK