Release v0.6.8

docs/RUNTIME.md

@@ -67,6 +67,9 @@ public:
     // Raw pointer for I/O memory binding
     T* raw_ptr();
 
+    // Const pointer to the value a READER should see (force-aware)
+    const T* read_ptr() const;
+
     // Cross-type converting constructor (enables implicit widening)
     template<typename U> IECVar(const IECVar<U>& other);
 };
@@ -95,6 +98,19 @@ Array elements store raw types; the calling variable wraps the entire array.
 
 Located variables (`AT %IX0.0`) use `raw_ptr()` to bind to an I/O image table at runtime. The code generator produces a descriptor array (`__located_vars_[]`) with metadata for each located variable (area, size, byte/bit indices) and accessor methods (`getLocatedVars()`, `getLocatedVarCount()`).
 
+### `raw_ptr()` vs `read_ptr()`
+
+Two pointers into an `IECVar`, and picking the wrong one is silently wrong for exactly one kind of variable.
+
+| | Points at | Use for |
+|---|---|---|
+| `raw_ptr()` | `value_`, always | **Binding** — the I/O image writes through it every scan |
+| `read_ptr()` | `forced_value_` while forced, `value_` otherwise | **Reading** — anything serving the value to a person or a protocol |
+
+`force()` writes through to `value_`, so for an ordinary variable the two agree the moment a force is applied. A **located** variable is the exception: the PLC program drives `value_` directly through the image binding every scan, without going through `set()`, so `raw_ptr()` would show the program's value while `get()` still reports the forced one. `read_ptr()` is `get()`'s semantics with `get()`'s copy removed, which is what an external reader needs to serve a value without copying it. `IECStringVar::c_str()` resolves the force the same way.
+
+The debug dispatch's pointer op (`handle_ptr`, and through it OPC-UA's zero-copy read) uses `read_ptr()` for that reason. The pointer it returns is valid only until the variable is next written **or its force state changes** — an `unforce()` moves the value back to a different object, and a retained pointer keeps reporting the stale forced one.
+
 ## Type Traits (`iec_traits.hpp`)
 
 Template traits for compile-time type categorization:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "strucpp",
-  "version": "0.6.4",
+  "version": "0.6.8",
   "description": "IEC 61131-3 Structured Text to C++ Compiler",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/backend/debug-table-gen.ts

@@ -187,6 +187,16 @@ const IEC_NAME_TO_TAG: Record<string, TagName> = {
 };
 
 /** Byte size for each IEC elementary type — authoritative for debug. */
+/**
+ * The string capacity the debug dispatch assumes.
+ *
+ * `debug_dispatch.hpp` casts every STRING/WSTRING leaf to
+ * `IECStringVar<254>` / `IECWStringVar<254>`. A leaf declared with any other
+ * length has its members at different offsets, so it cannot be registered —
+ * see the check in `visit()`. Keep in step with those casts.
+ */
+const DISPATCH_STRING_CAPACITY = 254;
+
 const IEC_NAME_TO_SIZE: Record<string, number> = {
   BOOL: 1,
   SINT: 1,
@@ -505,6 +515,42 @@ export function generateDebugTable(
 
     // Named elementary type (or alias thereof).
     if (IEC_NAME_TO_TAG[name] !== undefined) {
+      // A parameterised STRING(n) / WSTRING(n) cannot be dispatched. Every
+      // string op in `debug_dispatch.hpp` casts the leaf to
+      // `IECStringVar<254>` / `IECWStringVar<254>`, but codegen emits the
+      // DECLARED size (`IECStringVar<n>`), and `length_` sits at a different
+      // offset for every `n` — so the cast reads out of bounds. Measured on
+      // `s20 : STRING(20) := 'hello'`: `sizeof` 50 vs 518, and the length came
+      // back from 468 bytes past the end of the object. It read 0 there, but
+      // the value is undefined: with non-zero neighbouring memory it reads as
+      // the cap, and the read path would then serve that many bytes of
+      // adjacent memory.
+      //
+      // The dispatch has one function per TAG and `Entry` has nowhere to carry
+      // a per-leaf size, so making this work needs a per-leaf width in the
+      // table — a real change to a structure that is deliberately 6 bytes on
+      // AVR. Until then the leaf is SKIPPED rather than registered wrong:
+      // `skipped` is already surfaced to the caller, so this is a visible
+      // build warning instead of an out-of-bounds read at runtime.
+      //
+      // Nothing authored in the editor reaches this: its type picker is a
+      // closed list from the IEC registry, which carries `STRING` with no
+      // length parameter. It is hand-written ST compiled through the CLI that
+      // can declare `STRING(n)`.
+      if (
+        (name === "STRING" || name === "WSTRING") &&
+        typeRef.maxLength !== undefined &&
+        typeRef.maxLength !== DISPATCH_STRING_CAPACITY
+      ) {
+        skipped.push({
+          path,
+          reason:
+            `declared ${name}(${typeRef.maxLength}), but the debug dispatch ` +
+            `addresses strings as ${name}(${DISPATCH_STRING_CAPACITY}). ` +
+            `Declare it as a plain ${name} to expose it.`,
+        });
+        return;
+      }
       addLeaf(path, cppExpr, name, flags);
       return;
     }

src/index.ts

@@ -821,6 +821,22 @@ export function compile(
         severity: "warning",
       });
     }
+
+    // A leaf the walk could not register is not debuggable: it is absent from
+    // the debugger's watch list and from anything built on the debug table,
+    // OPC-UA included. That was silent — `skipped` was collected and dropped —
+    // so a variable simply was not there, with nothing in the build to say why
+    // or which. Same reasoning as `incomplete` above: the program still builds,
+    // but a drop nobody is told about is found later, at a debugger that shows
+    // nothing, with no thread back to the cause.
+    for (const item of dbg.skipped) {
+      pipeline.warnings.push({
+        message: `${item.path} is not debuggable: ${item.reason}`,
+        line: 0,
+        column: 0,
+        severity: "warning",
+      });
+    }
   }
 
   return {