@aryacode/dsh-engineering 0.4.22 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.5.0] - 2026-10-27
+
+Commissioned against the Laminator fixtures: a real Studio 5000 ACD exported to a 5.4 MB L5X, a
+real FactoryTalk View ME export, and two MotionWorks projects.
+
+### Fixed — FactoryTalk View could not read a real Studio export
+
+`ftview_open` reported **0 displays and 0 tags** for a genuine ME export. Five independent causes:
+
+- **The tag CSV delimiter was hard-coded to `;`** while Studio exports are comma-separated and use a
+  leading `;` only as a comment prefix, so every data row parsed as one cell. The separator is now
+  detected per line with quote awareness.
+- **The header was assumed to follow the `###002` line.** A real export writes the header first, then
+  `###002`, then `;Folders Section` / `;Tag Section` comments, and the parser took the first comment
+  for the header. It now finds a `Tag Name` header on either side of the version line.
+- **Short rows were rejected.** Studio omits trailing empty columns, so 29-column headers come with
+  23-column rows. Only over-long rows are errors now.
+- **`<gfx>` displays were refused.** ME display XML is `<gfx>` (Gfx-ME17.xsd), not `<display>`.
+- **UTF-16 files were decoded as UTF-8**, producing a root element of `\0g\0f\0x`; BOM sniffing now
+  selects UTF-16LE.
+
+Also normalised the host contract: `scanApplication` accepts the `FsTarget` that `fs.resolve`
+returns instead of calling string methods on it.
+
+Verified on `Laminator/HMI/Main`: **18 displays, 361 tags, 0 parse errors** (was 0 and 0). Reading a
+`<gfx>` export is supported; the staged edit tools were built for the `<display>` shape and are not
+verified to rewrite `<gfx>` objects.
+
+### Fixed — Studio 5000 checks drowned real findings in false positives
+
+`run_checks` on the Laminator export produced 562 findings, 315 of them "unresolved reference", on a
+project that compiles. Every one was an alias to module I/O (`In_FF_ModulePresent` →
+`FanFold_StraightCut_AENTR:2:I.7`): aliases carry no `DataType`, their targets are not declared
+`<Tag>`s, and the fast resolver stopped instead of falling back to the canonical one.
+
+- `resolveSymbol` now falls back to `resolveTag`, and an empty type with a trailing numeric part
+  resolves as a bit.
+- A member of a module-defined or opaque type (`Drive_MCFG.CommFLT`, `Axis_MAH.PC`) and `S:`/`R:`
+  system flags are reported as coverage limits, not unresolved references.
+
+**562 → 264 findings; unresolved 315 → 16**, with the unused-tag and multiple-write findings intact.
+
+### Fixed — Studio 5000 edits
+
+- **`add_tag` required a value for a scalar tag.** Studio defaults scalars to zero, so declaring a
+  plain REAL was impossible without inventing a value; `value` is now optional and still validated
+  when supplied.
+- **Live reads refused aliases.** `read_live_tags` and `poll_live_tags` ran the write rule, so
+  ordinary module-point BOOLs were rejected as "not a writable declared scalar". Reads and polls now
+  take an alias's type from the canonical resolver; writes still refuse an alias and name the tag to
+  write instead.
+- **`export_acd_to_l5x` failed when Studio had the ACD open.** The SDK opens the file itself, so the
+  normal case — the project the user is working on — failed with "being used by another process". The
+  export now copies the ACD and opens the copy, with the source hash re-checked before and after.
+
+Verified end to end on the Laminator export: `draft_tag` (REAL, no value) plus a rung replacement
+validated and applied to a 5,391,840-byte L5X.
+
+### Fixed — MotionWorks IEC
+
+- **`mw_get kind="block"` crashed with `KeyError: 'native_libraries'`.** The block interface is decoded
+  against the installed libraries as well as the saved project; the read service now supplies the live
+  inventory and falls back to the project's own registry when no IDE answers.
+- **`mw_edit_variables` refused with "Live declarations disagree with saved baseline"** and nothing
+  else. The refusal now names the missing, unexpected and changed declarations with their live and
+  saved values.
+
+Verified on both Laminator projects through the shipped engine: attach into
+`backups/motionworks/<project>/<stamp>/`, then `workflow_check`, `pous`, `read_text`, `validate`,
+`tasks`, `types`, `globals` and `library` all succeed (8 POUs, 5 tasks, ~170 globals, 297 types,
+23 blocks each).
+
+### Documentation
+
+- `docs/optix-netlogic.md`: how the FactoryTalk Optix NetLogic cheat sheet should be carried — a
+  pinned snapshot, a generated index, and one `optix_netlogic` retrieval tool, with the risk flags and
+  disclaimers the repository itself requires.
+
 ## [0.4.22] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -91,7 +91,9 @@ Where each surface actually stands, based on what has been exercised.
   downloads accepting only a verification id produced by a passed build
 - Live EtherNet/IP: polling, one-request batch reads of up to 64 tags, controller identity and clock, LAN discovery, and a bounded trend
 - Supervised live writes: `write_live_tag` and `write_controller_clock` need the row's `allowWrites` switch **and** per-call human approval, and report the value the controller reads back
-- FactoryTalk View ME: export reads, structural checks, comparison, staged display and HMI tag edits
+- FactoryTalk View ME: export reads, structural checks, comparison, staged display and HMI tag edits;
+  reads verified on a real Studio export (`<gfx>` displays and the comma-delimited tag CSV —
+  18 displays, 361 tags, no parse errors)
 - MotionWorks IEC: verified live against 3 Pro 1.19 — direct open with a verified pre-edit backup
   under `.motionworks/attached`, attach-without-reload to a project the IDE already has open, start,
   worksheet, close, saved-project reads, compile diagnostics, code replacement, declaration add, POU
@@ -118,6 +120,7 @@ the lean profile is the one that turns them off.
 
 | Version | What landed |
 |---|---|
+| **0.5.0** | Commissioned on real files: FactoryTalk View reads genuine Studio exports (`<gfx>` displays, comma CSVs, UTF-16) instead of reporting zero; L5X alias resolution cuts 315 false "unresolved reference" findings to 16 on a 1279-tag project; `add_tag` no longer demands a value; a locked ACD exports from a copy |
 | **0.4.17** | MotionWorks edits the real project again: the pre-edit backup is written where the bridge and engine verify it, an already-open project is attached instead of reloaded, and `mw_get` returns the body hash the edit takes |
 | **0.4.15** | Every tool surface ships on by default; the row Configure pages switch them off |
 | **0.4.4** | One row per product: five rows, optional surfaces moved into each row's config |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.4.22",
+  "version": "0.5.0",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",

package/vendor/ftview/SKILL.md

@@ -13,6 +13,12 @@ A staged edit is written to a NEW export folder; the source is never modified. T
 a manual import for a human; it does not drive Studio, contact a terminal, or decode MER or MED
 databases.
 
+Both export shapes are read: the Studio ME export (`<gfx>` displays, `Gfx-ME17.xsd`, a comma-delimited
+`Tags/*.csv` with its header before the `###002` line and `;` comment rows) and the older
+`<display>`-root files. Staged attribute edits were built for the `<display>` shape; on a `<gfx>`
+export, read and verify with this surface and make the change in Studio, or confirm the edit applied
+before relying on it.
+
 ## Backups
 
 Every engineering product backs up into the same tree, so a backup means one place whichever surface

package/vendor/ftview/lib/model.d.ts

@@ -8,7 +8,7 @@
  *
  * @module dsh-engineering-ftview/model
  */
-import { type FsService } from './core.ts';
+import { type FsService, type FsTarget } from './core.ts';
 /** One row of the HMI tag CSV, keyed by its canonical columns. */
 export interface TagRow {
     readonly name: string;
@@ -51,11 +51,16 @@ export interface TagCsv {
     readonly rows: readonly TagRow[];
     readonly errors: readonly string[];
 }
-/** Split one semicolon-separated CSV line, honouring double quotes. */
+/** Split one CSV line, honouring double quotes and the line's own separator. */
 export declare function splitCsv(line: string): string[];
 /**
  * Parse the HMI tag CSV.
  *
+ * The ME export writes an optional header first, then a `###002` version line, then
+ * `;` comment/section lines and the data rows. Earlier builds assumed the header
+ * followed the version line and treated `;Folders Section` as the header, so a real
+ * export parsed as zero tags.
+ *
  * @param text - Whole CSV file.
  * @returns Rows plus structural errors; a file with no `###002` marker yields no rows.
  */
@@ -77,4 +82,4 @@ export declare function parseDisplay(file: string, text: string): DisplayFile;
  * @param maxFiles - Largest number of display/tag files accepted.
  * @returns The scanned application.
  */
-export declare function scanApplication(fs: FsService, root: string, signal: AbortSignal | undefined, maxFiles: number): Promise<Application>;
+export declare function scanApplication(fs: FsService, root: string | FsTarget, signal: AbortSignal | undefined, maxFiles: number): Promise<Application>;

package/vendor/ftview/lib/model.js

@@ -14,8 +14,30 @@ import { XMLParser } from 'fast-xml-parser';
 import { EngineeringError } from "./core.js";
 /** Attribute prefix the XML parser uses. */
 const ATTRIBUTE = '@_';
-/** Split one semicolon-separated CSV line, honouring double quotes. */
+/**
+ * Pick the field separator of one line.
+ *
+ * A Studio ME tag export is comma-separated and uses a leading `;` as a comment
+ * prefix; older/semicolon exports exist too. Splitting on a fixed `;` turned every
+ * real row into one cell, so a genuine export parsed as zero tags.
+ */
+function delimiterOf(line) {
+    let commas = 0;
+    let semicolons = 0;
+    let quoted = false;
+    for (const character of line) {
+        if (character === '"')
+            quoted = !quoted;
+        else if (!quoted && character === ',')
+            commas += 1;
+        else if (!quoted && character === ';')
+            semicolons += 1;
+    }
+    return commas >= semicolons ? ',' : ';';
+}
+/** Split one CSV line, honouring double quotes and the line's own separator. */
 export function splitCsv(line) {
+    const delimiter = delimiterOf(line);
     const cells = [];
     let current = '';
     let quoted = false;
@@ -38,7 +60,7 @@ export function splitCsv(line) {
         else if (character === '"') {
             quoted = true;
         }
-        else if (character === ';') {
+        else if (character === delimiter) {
             cells.push(current);
             current = '';
         }
@@ -49,32 +71,47 @@ export function splitCsv(line) {
     cells.push(current);
     return cells;
 }
-/** Decode bytes as UTF-8, dropping a byte-order mark. */
+/** Decode bytes as UTF-8 or UTF-16, dropping a byte-order mark. */
 function decode(bytes) {
+    // Studio writes most exports as UTF-8, but some generated files (BatchImport) are
+    // UTF-16LE. Decoding those as UTF-8 produced a root element of "\0g\0f\0x".
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
+        return new TextDecoder('utf-16le').decode(bytes.subarray(2));
     const text = new TextDecoder('utf-8').decode(bytes);
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
 /**
  * Parse the HMI tag CSV.
  *
+ * The ME export writes an optional header first, then a `###002` version line, then
+ * `;` comment/section lines and the data rows. Earlier builds assumed the header
+ * followed the version line and treated `;Folders Section` as the header, so a real
+ * export parsed as zero tags.
+ *
  * @param text - Whole CSV file.
  * @returns Rows plus structural errors; a file with no `###002` marker yields no rows.
  */
 export function parseTagCsv(text) {
     const lines = text.split(/\r?\n/);
+    const isComment = (line) => line.trimStart().startsWith(';');
     const versionLine = lines.findIndex(line => line.includes('###002'));
     if (versionLine < 0) {
         return { rows: [], errors: ['Unsupported tag CSV: the `###002` version line is missing.'] };
     }
-    const headerIndex = lines.findIndex((line, index) => index > versionLine && line.trim() !== '');
+    const headerCells = (line) => splitCsv(line).map((cell, index) => {
+        const trimmed = cell.trim();
+        return index === 0 ? trimmed.replace(/^;/u, '').trim() : trimmed;
+    });
+    // Prefer a real header before the version line; fall back to the first non-comment
+    // line after it for files that put the header last.
+    const before = lines.slice(0, versionLine).findIndex(line => headerCells(line).includes('Tag Name'));
+    const after = lines.findIndex((line, index) => index > versionLine && line.trim() !== '' && !isComment(line) && headerCells(line).includes('Tag Name'));
+    const headerIndex = before >= 0 ? before : after;
     if (headerIndex < 0) {
-        return { rows: [], errors: ['Unsupported tag CSV: no header row follows the version line.'] };
+        return { rows: [], errors: ['Unsupported tag CSV: no header row with a `Tag Name` column was found.'] };
     }
-    const header = splitCsv(lines[headerIndex]).map(cell => cell.trim());
+    const header = headerCells(lines[headerIndex]);
     const nameIndex = header.indexOf('Tag Name');
-    if (nameIndex < 0) {
-        return { rows: [], errors: ['Unsupported tag CSV: the header has no `Tag Name` column.'] };
-    }
     const descriptionIndex = header.indexOf('Tag Description');
     const typeIndex = header.indexOf('Tag Type');
     const rows = [];
@@ -82,11 +119,15 @@ export function parseTagCsv(text) {
     const seen = new Set();
     for (let index = headerIndex + 1; index < lines.length; index += 1) {
         const line = lines[index];
-        if (line.trim() === '')
+        if (line.trim() === '' || isComment(line))
+            continue;
+        if (index < versionLine)
             continue;
         const cells = splitCsv(line);
-        if (cells.length < header.length) {
-            errors.push(`Row ${index + 1}: expected ${header.length} columns, found ${cells.length}.`);
+        // Studio omits trailing empty columns, so a data row is legitimately shorter
+        // than the header; only a longer row is malformed.
+        if (cells.length > header.length) {
+            errors.push(`Row ${index + 1}: expected at most ${header.length} columns, found ${cells.length}.`);
             continue;
         }
         const raw = {};
@@ -165,7 +206,9 @@ export function parseDisplay(file, text) {
         if (rootKey === undefined)
             return { file, name: fallbackName, objects: [], parseError: 'The file has no root element.' };
         const rootNode = parsed[rootKey];
-        if (!/display/iu.test(rootKey)) {
+        // ME display files use <gfx> (Gfx-ME17.xsd) in a Studio export; some hand-made
+        // or older files use a <display> root. Both are display files.
+        if (!/display/iu.test(rootKey) && !/^gfx$/iu.test(rootKey)) {
             return { file, name: fallbackName, objects: [], parseError: `Root element ${rootKey} is not an ME display.` };
         }
         const root = (rootNode ?? {});
@@ -233,13 +276,17 @@ async function walk(fs, root, relative, signal, visit, budget) {
  * @returns The scanned application.
  */
 export async function scanApplication(fs, root, signal, maxFiles) {
+    // The host's `fs.resolve` returns an FsTarget, while the walk below composes
+    // string paths for `listDir`/`readBytes`. Normalise once here: passing the target
+    // straight into the walker crashed every open on a host that returns one.
+    const base = typeof root === 'string' ? root : root.displayPath;
     const displays = [];
     const tags = [];
     const tagFiles = [];
     const tagErrors = [];
     const diagnostics = [];
     const files = [];
-    await walk(fs, root, '', signal, async (file, absolute) => {
+    await walk(fs, base, '', signal, async (file, absolute) => {
         const bytes = await fs.readBytes(absolute, signal, 32 * 1024 * 1024);
         const text = decode(bytes);
         files.push({ file, bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') });
@@ -262,6 +309,6 @@ export async function scanApplication(fs, root, signal, maxFiles) {
         }
         displays.push(display);
     }, { count: 0, max: maxFiles });
-    const name = root.replace(/[\\/]$/u, '').split(/[\\/]/u).pop() ?? root;
-    return { root, name, displays, tags, tagFiles, tagErrors, diagnostics, files };
+    const name = base.replace(/[\\/]$/u, '').split(/[\\/]/u).pop() ?? base;
+    return { root: base, name, displays, tags, tagFiles, tagErrors, diagnostics, files };
 }

package/vendor/l5x/lib/engine/analysis.d.ts

@@ -15,7 +15,15 @@ export interface Evidence {
     readonly confidence: 'high' | 'medium' | 'low';
     readonly context: string;
 }
-/** Resolve only declarations proven by the export. Never guess an absent member. */
+/**
+ * Resolve a written symbol to a canonical declaration.
+ *
+ * The fast path walks the declaration and alias tables. It stops where the
+ * operand behind an alias is not a declared `<Tag>` — module I/O such as
+ * `FanFold_StraightCut_AENTR:2:I.7` — which is common in a real project: those
+ * references are proven by the export, not missing. Fall back to the canonical
+ * resolver (the one behind `resolve_tag`) before declaring a symbol unresolved.
+ */
 export declare function resolveSymbol(document: L5xDocument, scope: string, symbol: string): string | undefined;
 export declare function evidenceOf(project: ProjectSnapshot): readonly Evidence[];
 export declare function findReferences(project: ProjectSnapshot, symbol: string, scope?: string): readonly Evidence[];

package/vendor/l5x/lib/engine/analysis.js

@@ -1,6 +1,7 @@
 import { controllerElementOf } from "../model/parse.js";
 import { elementChildren, firstChild } from "../model/xml.js";
 import { memberOf } from "./details.js";
+import { resolveTag } from "./tag-resolution.js";
 const TOKEN = /[A-Za-z_][A-Za-z0-9_]*(?::[A-Za-z0-9_]+)*(?:\[[^\]]+\])?(?:\.[A-Za-z0-9_]+(?:\[[^\]]+\])?)*/gu;
 const LADDER = /([A-Za-z_][A-Za-z0-9_]*)\s*\(([^()]*)\)/gu;
 const READ_OPS = new Set(['XIC', 'XIO', 'EQU', 'EQ', 'NEQ', 'NE', 'GRT', 'GT', 'GEQ', 'GE', 'LES', 'LT', 'LEQ', 'LE', 'LIM', 'LIMIT', 'CMP']);
@@ -82,8 +83,24 @@ function tableOf(document) {
     tables.set(document, table);
     return table;
 }
-/** Resolve only declarations proven by the export. Never guess an absent member. */
+/**
+ * Resolve a written symbol to a canonical declaration.
+ *
+ * The fast path walks the declaration and alias tables. It stops where the
+ * operand behind an alias is not a declared `<Tag>` — module I/O such as
+ * `FanFold_StraightCut_AENTR:2:I.7` — which is common in a real project: those
+ * references are proven by the export, not missing. Fall back to the canonical
+ * resolver (the one behind `resolve_tag`) before declaring a symbol unresolved.
+ */
 export function resolveSymbol(document, scope, symbol) {
+    const direct = resolveSymbolDirect(document, scope, symbol);
+    if (direct !== undefined)
+        return direct;
+    const resolution = resolveTag(document, scope, symbol);
+    return resolution.resolved ? resolution.canonical : undefined;
+}
+/** Resolve only declarations proven by the export. Never guess an absent member. */
+function resolveSymbolDirect(document, scope, symbol) {
     const table = tableOf(document);
     const aoi = document.aois.find(entry => entry.name === scope);
     const parts = symbol.replace(/\[[^\]]+\]/gu, '').split('.');
@@ -96,6 +113,7 @@ export function resolveSymbol(document, scope, symbol) {
     let tag = table.tags.get(tagKey(scope, base)) ?? table.tags.get(tagKey('controller', base));
     if (tag === undefined)
         return undefined;
+    const declared = tag;
     let resolvedBase = tag.name;
     const seen = new Set();
     while (tag !== undefined) {
@@ -111,8 +129,12 @@ export function resolveSymbol(document, scope, symbol) {
         if (aliasBase === undefined)
             break;
         tag = table.tags.get(tagKey(tag.scope, aliasBase)) ?? table.tags.get(tagKey('controller', aliasBase));
+        // A module I/O operand (`Local:1:I.Data[0].5`) is not a declared <Tag>: the
+        // export proves the alias, not the operand behind it. Resolving to the alias
+        // is what stops 315 real references being reported as unresolved, while
+        // resolveTag still canonicalises the operand for callers that ask to resolve.
         if (tag === undefined)
-            return undefined;
+            return `${declared.scope}::${declared.name}${parts.length > 0 ? `.${parts.join('.')}` : ''}`;
     }
     const path = [...resolvedBase.split('.').slice(1), ...parts];
     if (path.length > 0) {
@@ -120,7 +142,10 @@ export function resolveSymbol(document, scope, symbol) {
         for (const [index, part] of path.entries()) {
             if (/^\d+$/u.test(part)) {
                 // `Alarm[8].12` is bit 12 of an integer element; nothing may follow it.
-                if (index !== path.length - 1 || !INTEGER_TYPES.has(type?.toUpperCase() ?? ''))
+                // Module I/O data carries no builtin DataType in the export, so an empty
+                // type with a trailing numeric part is still a bit of that module data.
+                const known = type === undefined || type === '' ? undefined : type.toUpperCase();
+                if (index !== path.length - 1 || (known !== undefined && !INTEGER_TYPES.has(known)))
                     return undefined;
                 type = 'BOOL';
                 continue;

package/vendor/l5x/lib/engine/change-set.js

@@ -137,11 +137,12 @@ function parseOne(value, declaredTypes) {
             if (dimensions !== undefined && row.value !== undefined)
                 throw new EngineeringError('INVALID_CHANGE_SET', 'An array tag takes Studio default element values; omit value');
             if (dimensions === undefined && scalar) {
-                if (row.value === undefined)
-                    throw new EngineeringError('INVALID_CHANGE_SET', 'value is required for a scalar tag; omit value for an array or declared-type tag');
-                if (!fitsScalar(dataType, row.value))
+                // A Logix scalar defaults to its type's zero. Requiring `value` here made
+                // the ordinary "declare a REAL" operation invalid, which is what failed
+                // two add_tag operations in a live session.
+                if (row.value !== undefined && !fitsScalar(dataType, row.value))
                     throw new EngineeringError('INVALID_CHANGE_SET', `value ${String(row.value)} does not fit ${dataType}; BOOL accepts 0/1 and integer types accept their signed/unsigned range`);
-                return { operation: row.operation, scope: identifier(row, 'scope'), name: identifier(row, 'name'), data_type: dataType, value: row.value, description: text(row, 'description'), ...(access === undefined ? {} : { external_access: access }) };
+                return { operation: row.operation, scope: identifier(row, 'scope'), name: identifier(row, 'name'), data_type: dataType, ...(row.value === undefined ? {} : { value: row.value }), description: text(row, 'description'), ...(access === undefined ? {} : { external_access: access }) };
             }
             return { operation: row.operation, scope: identifier(row, 'scope'), name: identifier(row, 'name'), data_type: dataType, ...(dimensions === undefined ? {} : { dimensions }), description: text(row, 'description'), ...(access === undefined ? {} : { external_access: access }) };
         }

package/vendor/l5x/lib/engine/cip-request.d.ts

@@ -17,6 +17,7 @@ export interface ScalarTag {
     name: string;
     program?: string;
     data_type: Scalar;
+    alias_for?: string;
 }
 /**
  * Resolve the controller address and slot both read and write share.

package/vendor/l5x/lib/engine/cip-request.js

@@ -11,6 +11,7 @@ import { isIPv4 } from 'node:net';
 import { EngineeringError } from "../session.js";
 import { aliasesOf } from "./configuration.js";
 import { findReferences } from "./analysis.js";
+import { resolveTag } from "./tag-resolution.js";
 import { controllerElementOf } from "../model/parse.js";
 import { elementChildren, firstChild } from "../model/xml.js";
 /** Scalar types this surface can read and write. */
@@ -18,6 +19,74 @@ const SCALARS = ['BOOL', 'INT', 'DINT', 'REAL'];
 /** Integer ranges enforced before a write leaves the machine. */
 const RANGES = { INT: [-32768, 32767], DINT: [-2147483648, 2147483647] };
 const isScalar = (value) => typeof value === 'string' && SCALARS.includes(value);
+/** Resolve one entry against the export: name, scope, declaration and alias target. */
+function declaredTag(project, entry, errorCode = 'UNSUPPORTED_WRITE_TAG') {
+    if (!entry || typeof entry !== 'object' || !('name' in entry) || typeof entry.name !== 'string'
+        || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
+        || !Object.keys(entry).every(key => key === 'name' || key === 'scope'))
+        throw new EngineeringError(errorCode, 'Each tag needs an exact tag name and optional scope only');
+    const scope = 'scope' in entry ? entry.scope : 'controller';
+    if (typeof scope !== 'string' || (scope !== 'controller' && !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(scope)))
+        throw new EngineeringError('INVALID_POLL', 'scope must be controller or an exact program name');
+    const declared = project.document.tags.find(tag => tag.name === entry.name && tag.scope === scope);
+    const controller = controllerElementOf(project.document);
+    const programs = firstChild(controller, 'Programs');
+    const container = scope === 'controller' ? controller : programs === undefined ? undefined
+        : elementChildren(programs, 'Program').find(program => program.attrs.Name === scope);
+    const tagContainer = container === undefined ? undefined : firstChild(container, 'Tags');
+    const declaration = tagContainer === undefined ? undefined : elementChildren(tagContainer, 'Tag').find(tag => tag.attrs.Name === entry.name);
+    const dimensions = declaration?.attrs.Dimensions ?? declaration?.attrs.Dimension ?? '';
+    if (!declared) {
+        throw new EngineeringError(errorCode, `${String(entry.name)} is not a declared tag in this export`, 'Open the export that declares it, or check the name with list_components kind="tag".');
+    }
+    return {
+        name: declared.name,
+        scope,
+        dataType: declared.dataType,
+        ...(declaration?.attrs.AliasFor === undefined ? {} : { aliasFor: declaration.attrs.AliasFor }),
+        dimensions,
+        ...(declaration?.attrs.ExternalAccess === undefined ? {} : { externalAccess: declaration.attrs.ExternalAccess }),
+    };
+}
+/**
+ * Resolve one *readable* scalar.
+ *
+ * Reading is not writing: an alias resolves to the same value the controller
+ * serves under either name, and ExternalAccess="None" only stops writes. Refusing
+ * aliases here made the ordinary case — a BOOL alias onto a module point — look
+ * like a mistyped tag.
+ */
+function resolveReadable(project, entry, errorCode = 'UNSUPPORTED_WRITE_TAG') {
+    const tag = declaredTag(project, entry, errorCode);
+    // An alias carries no DataType of its own. resolveTag follows it to the operand
+    // behind it, including module I/O that is not a declared <Tag> — the same
+    // resolution the resolve_tag tool reports.
+    const resolution = isScalar(tag.dataType) ? undefined : resolveTag(project.document, tag.scope, tag.name);
+    const type = isScalar(tag.dataType) ? tag.dataType
+        : resolution?.resolved === true && isScalar(resolution.data_type) ? resolution.data_type : undefined;
+    if (!isScalar(type)) {
+        throw new EngineeringError(errorCode, `${tag.name} is ${tag.dataType || 'an undeclared type'}; this surface reads BOOL, INT, DINT and REAL scalars`, 'Read a scalar tag, or use the export tools for structured values.');
+    }
+    if (tag.dimensions !== '' && tag.dimensions !== '0') {
+        throw new EngineeringError(errorCode, `${tag.name} is an array (${tag.dimensions}); this surface reads one scalar at a time`, 'Read one element with a name the controller declares, or use the export tools for the array.');
+    }
+    return { name: tag.name, ...(tag.scope === 'controller' ? {} : { program: tag.scope }), data_type: type, ...(tag.aliasFor === undefined ? {} : { alias_for: tag.aliasFor }) };
+}
+/**
+ * Resolve one *writable* scalar: no alias, external access, declared range.
+ */
+function resolveWritable(project, entry) {
+    const tag = declaredTag(project, entry);
+    if (aliasesOf(project.document).has(`${tag.scope}::${tag.name}`))
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${tag.name} is an alias; write the tag it points at`, 'Read aliases freely; a write must name the declared tag so the controller changes one known operand.');
+    if (!isScalar(tag.dataType))
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${tag.name} is ${tag.dataType || 'an undeclared type'}; writes accept BOOL, INT, DINT and REAL scalars`, 'Read the value, or use the export tools for structured values.');
+    if (tag.dimensions !== '' && tag.dimensions !== '0')
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${tag.name} is an array (${tag.dimensions}); write one scalar at a time`, 'Write one element the controller declares, or use the export tools for the array.');
+    if (tag.externalAccess === 'None')
+        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${tag.name} is ExternalAccess="None"; the controller refuses external writes`, 'Change ExternalAccess in Studio, or write a different tag.');
+    return { name: tag.name, ...(tag.scope === 'controller' ? {} : { program: tag.scope }), data_type: tag.dataType };
+}
 /**
  * Resolve the controller address and slot both read and write share.
  * @param input - Tool arguments.
@@ -48,7 +117,7 @@ export function batchReadRequest(project, input, config, maxBatch) {
     const raw = typeof input.tags_json === 'string' ? JSON.parse(input.tags_json) : null;
     if (!Array.isArray(raw) || raw.length < 1 || raw.length > maxBatch)
         throw new EngineeringError('INVALID_POLL', `tags must contain 1 through ${String(maxBatch)} declared scalar tags`);
-    const tags = raw.map((entry) => resolveScalar(project, entry));
+    const tags = raw.map((entry) => resolveReadable(project, entry));
     const seen = new Set();
     for (const tag of tags) {
         const key = `${tag.program ?? 'controller'}::${tag.name}`.toLowerCase();
@@ -78,7 +147,7 @@ export function writableTagRequest(project, input, config) {
     const target = controllerTarget(input, config);
     const name = input.name;
     const program = input.program;
-    const tag = resolveScalar(project, { name, ...(program === undefined ? {} : { scope: program }) });
+    const tag = resolveWritable(project, { name, ...(program === undefined ? {} : { scope: program }) });
     const value = input.value;
     if (tag.data_type === 'BOOL') {
         if (typeof value !== 'boolean')
@@ -108,27 +177,3 @@ export function discoverRequest(input, config) {
         throw new EngineeringError('INVALID_POLL', 'duration_seconds must be an integer between 1 and 15');
     return { request: { op: 'discover', duration: seconds * 1000, timeout: config.requestTimeoutMs } };
 }
-/** Resolve one declared scalar (never an alias, array or unknown tag). */
-function resolveScalar(project, entry) {
-    if (!entry || typeof entry !== 'object' || !('name' in entry) || typeof entry.name !== 'string'
-        || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
-        || !Object.keys(entry).every(key => key === 'name' || key === 'scope'))
-        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', 'Each tag needs an exact scalar name and optional scope only');
-    const scope = 'scope' in entry ? entry.scope : 'controller';
-    if (typeof scope !== 'string' || (scope !== 'controller' && !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(scope)))
-        throw new EngineeringError('INVALID_POLL', 'scope must be controller or an exact program name');
-    const declared = project.document.tags.find(tag => tag.name === entry.name && tag.scope === scope);
-    const controller = controllerElementOf(project.document);
-    const programs = firstChild(controller, 'Programs');
-    const container = scope === 'controller' ? controller : programs === undefined ? undefined
-        : elementChildren(programs, 'Program').find(program => program.attrs.Name === scope);
-    const tagContainer = container === undefined ? undefined : firstChild(container, 'Tags');
-    const declaration = tagContainer === undefined ? undefined : elementChildren(tagContainer, 'Tag').find(tag => tag.attrs.Name === entry.name);
-    const dimensions = declaration?.attrs.Dimensions ?? declaration?.attrs.Dimension ?? '';
-    if (!declared || aliasesOf(project.document).has(`${scope}::${declared.name}`)
-        || !isScalar(declared.dataType)
-        || (dimensions !== '' && dimensions !== '0')
-        || declaration?.attrs.ExternalAccess === 'None')
-        throw new EngineeringError('UNSUPPORTED_WRITE_TAG', `${String(entry.name)} is not a writable declared scalar BOOL, INT, DINT or REAL`, 'Reads accept the same tags; writes additionally need ExternalAccess and no array dimensions.');
-    return { name: declared.name, ...(scope === 'controller' ? {} : { program: scope }), data_type: declared.dataType };
-}

package/vendor/l5x/lib/engine/direct-polling.js

@@ -2,8 +2,8 @@
 import { Worker } from 'node:worker_threads';
 import { isIPv4 } from 'node:net';
 import { EngineeringError } from "../session.js";
-import { aliasesOf } from "./configuration.js";
 import { findReferences } from "./analysis.js";
+import { resolveTag } from "./tag-resolution.js";
 import { controllerElementOf } from "../model/parse.js";
 import { elementChildren, firstChild } from "../model/xml.js";
 /**
@@ -49,15 +49,21 @@ export function pollingRequest(project, input, config) {
         const tagContainer = container === undefined ? undefined : firstChild(container, 'Tags');
         const declaration = tagContainer === undefined ? undefined : elementChildren(tagContainer, 'Tag').find(tag => tag.attrs.Name === entry.name);
         const dimensions = declaration?.attrs.Dimensions ?? declaration?.attrs.Dimension ?? '';
-        if (!declared || aliasesOf(project.document).has(`${scope}::${declared.name}`)
-            || !['BOOL', 'INT', 'DINT', 'REAL'].includes(declared.dataType)
-            || dimensions !== '' && dimensions !== '0' || declaration?.attrs.ExternalAccess === 'None')
-            throw new EngineeringError('UNSUPPORTED_POLL_TAG', 'Select a declared non-alias scalar BOOL, INT, DINT, or REAL');
+        // A poll is a read: an alias is a normal operand, and ExternalAccess only
+        // stops writes. Refusing aliases made every module-point BOOL unmonitorable.
+        let type = ['BOOL', 'INT', 'DINT', 'REAL'].includes(declared?.dataType ?? '') ? declared?.dataType ?? '' : '';
+        if (type === '' && declared !== undefined) {
+            const resolution = resolveTag(project.document, scope, declared.name);
+            if (resolution.resolved && resolution.data_type !== undefined && ['BOOL', 'INT', 'DINT', 'REAL'].includes(resolution.data_type))
+                type = resolution.data_type;
+        }
+        if (!declared || type === '' || (dimensions !== '' && dimensions !== '0'))
+            throw new EngineeringError('UNSUPPORTED_POLL_TAG', 'Select a declared scalar BOOL, INT, DINT, or REAL (aliases are read through; arrays are refused)');
         const key = `${scope}::${declared.name}`.toLowerCase();
         if (seen.has(key))
             throw new EngineeringError('INVALID_POLL', 'Duplicate watch tag');
         seen.add(key);
-        return { name: declared.name, ...(scope === 'controller' ? {} : { program: scope }), data_type: declared.dataType };
+        return { name: declared.name, ...(scope === 'controller' ? {} : { program: scope }), data_type: type };
     });
     const request = { ip, slot, tags, samples, interval, timeout: config.requestTimeoutMs };
     return { request, evidence: tags.map(tag => ({ tag: tag.name, scope: tag.program ?? 'controller',

package/vendor/l5x/lib/engine/review.js

@@ -1,4 +1,4 @@
-import { evidenceOf } from "./analysis.js";
+import { evidenceOf, resolveSymbol } from "./analysis.js";
 import { engineeringTags, moduleConfigurations } from "./configuration.js";
 function changes(component, before, after, key) {
     const old = new Map(before.map(value => [key(value), value]));
@@ -71,6 +71,17 @@ export function runChecks(project, baseline) {
     for (const ref of references) {
         if (ref.resolved !== undefined || ref.access === 'call' || ref.access === 'unknown')
             continue;
+        // A member of a module-defined or otherwise opaque type (`Drive_MCFG.CommFLT`,
+        // `Axis_MAH.PC`) is not in the export's DataTypes, so this model cannot prove
+        // it. The base tag is declared, the member is not decodable: that is a coverage
+        // limit, not an unresolved reference, and reporting it drowned the real findings
+        // — 315 of them on one project that compiles. `S:`/`R:` system flags are the
+        // same case: defined by the controller, absent from the export.
+        const base = ref.symbol.split('.')[0] ?? ref.symbol;
+        const systemFlag = /^[SR]:/iu.test(ref.symbol);
+        const baseDeclared = systemFlag ? undefined : resolveSymbol(doc, ref.scope, base);
+        if (baseDeclared !== undefined)
+            continue;
         const key = `${ref.scope}::${ref.symbol}`;
         unresolved.set(key, [...unresolved.get(key) ?? [], ref]);
     }

package/vendor/l5x/lib/engine/studio-sdk.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, extname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { EngineeringError } from "../session.js";
 import { documentRoot, firstChild, optionalAttribute, parseXml } from "../model/xml.js";
@@ -135,18 +135,36 @@ export async function exportAcdToL5x(acdPath, outputPath, signal) {
         throw new EngineeringError('OUTPUT_DIRECTORY', 'Output directory does not exist');
     const sourceHash = createHash('sha256').update(await readFile(source)).digest('hex');
     await ensureBridge(availability, signal);
-    const result = await runBridge([bridgeDll, 'export-l5x', source, output], 240_000, signal);
-    if (result.code !== 0 || !result.output.includes('EXPORTED_L5X_SUCCEEDED'))
-        throw new EngineeringError('L5X_EXPORT_FAILED', result.output);
+    let result = await runBridge([bridgeDll, 'export-l5x', source, output], 240_000, signal);
+    // A project open in Studio 5000 holds an exclusive handle on its ACD, and the
+    // SDK opens the file itself, so the ordinary case - the project the user is
+    // working on - failed with "being used by another process". Exporting reads a
+    // snapshot: copy the ACD and open the copy. Nothing is written to the original.
+    let scratch;
+    if ((result.code !== 0 || !result.output.includes('EXPORTED_L5X_SUCCEEDED')) && /being used by another process|could not open file/iu.test(result.output)) {
+        const scratchDir = join(tmpdir(), `arya-l5x-export-${process.pid}-${Date.now()}`);
+        await mkdir(scratchDir, { recursive: true });
+        scratch = join(scratchDir, basename(source));
+        await copyFile(source, scratch);
+        if (createHash('sha256').update(await readFile(scratch)).digest('hex') !== sourceHash) {
+            throw new EngineeringError('ACD_CHANGED', 'The ACD changed while it was being copied; save or close it in Studio 5000 and retry');
+        }
+        result = await runBridge([bridgeDll, 'export-l5x', scratch, output], 240_000, signal);
+    }
+    if (result.code !== 0 || !result.output.includes('EXPORTED_L5X_SUCCEEDED')) {
+        throw new EngineeringError('L5X_EXPORT_FAILED', result.output, 'Close the project in Studio 5000, or retry: a locked ACD is exported from a private copy.');
+    }
     if (createHash('sha256').update(await readFile(source)).digest('hex') !== sourceHash)
         throw new EngineeringError('ACD_CHANGED', 'Source ACD changed during export; reopen and export an unchanged source copy');
+    if (scratch !== undefined)
+        await rm(dirname(scratch), { recursive: true, force: true }).catch(() => { });
     const bytes = await readFile(output);
     if (bytes.length === 0 || !bytes.toString('utf8', 0, Math.min(bytes.length, 2048)).includes('<RSLogix5000Content')) {
         throw new EngineeringError('L5X_EXPORT_INVALID', 'SDK export did not produce a recognizable L5X file');
     }
     return { source_acd: source, source_sha256: sourceHash, output_path: output, output_bytes: bytes.length,
         output_sha256: createHash('sha256').update(bytes).digest('hex'), exported_at: new Date().toISOString(),
-        controller_operation: 'none', studio_review: 'required' };
+        ...(scratch === undefined ? {} : { exported_from_copy: true }), controller_operation: 'none', studio_review: 'required' };
 }
 function checkProject(project, availability) {
     if (!availability.available)

package/vendor/mwi/code/mw_code.py

@@ -78,7 +78,10 @@ def verb_structure_snapshot(req):
 
 def verb_block_interface(req):
     from motionworks_iec_mcp.block_interfaces import inspect
-    return _ok(**inspect(Path(req['project']),req['native_libraries'],req.get('name'),req.get('library')))
+    # The inventory is optional at this boundary: a read with no live IDE answers
+    # from the project's own registry, and a saved vendor reference it cannot match
+    # is reported as that, instead of a KeyError the caller cannot act on.
+    return _ok(**inspect(Path(req['project']),req.get('native_libraries') or [],req.get('name'),req.get('library')))
 
 def verb_installed_help(req):
     from motionworks_iec_mcp.installed_help import search

package/vendor/mwi/legacy/native-variables.js

@@ -39,7 +39,15 @@ export async function nativeVariableChange(args,{status,saved,snapshot,snapshotS
   const live=snapshotSaved?combined:await snapshot();
   const nativeRows=savedProjection(live.variables);
   const aligned=compare(before.variables,nativeRows);
-  if(!aligned.accepted)throw new Error('Live declarations disagree with saved baseline; no native action performed');
+  // Name the difference. A bare "disagree" left four live attempts with nothing to
+  // act on: the caller cannot tell a description trim from a missing declaration.
+  const detail=a=>[
+    ...(a.missing?.length?['missing '+a.missing.slice(0,5).join(', ')]:[]),
+    ...(a.unexpected?.length?['unexpected '+a.unexpected.slice(0,5).join(', ')]:[]),
+    ...(a.changed??[]).slice(0,5).map(c=>`${c.name} differs in ${c.fields.join('/')} (live ${JSON.stringify(c.expected)} vs saved ${JSON.stringify(c.saved)})`),
+    ...(a.errors??[]).slice(0,3),
+  ].join('; ');
+  if(!aligned.accepted)throw new Error('Live declarations disagree with saved baseline; no native action performed'+(detail(aligned)?': '+detail(aligned):''));
   const plan=variableChangePlan(before.variables,args,live.groups.map(g=>g.name));
   if(args.declaration?.section==='VAR_EXTERNAL') {
     const global=await globals();

package/vendor/mwi/lib/read/service.d.ts

@@ -30,10 +30,16 @@ export declare const GET_KINDS: readonly ["pou", "type", "task", "block", "eip"]
 /** The saved-project read service. */
 export declare class ReadService {
     private readonly engine;
+    private readonly nativeLibraries?;
     /**
      * @param engine - Code engine over the project files.
+     * @param nativeLibraries - Live IDE library inventory, when the host has one.
+     *   A block interface is decoded against the installed libraries as well as the
+     *   saved project, so without it a vendor block cannot be resolved. Reads stay
+     *   usable without an IDE: the provider returns nothing and the engine answers
+     *   for the project's own registry alone.
      */
-    constructor(engine: ReadEngine);
+    constructor(engine: ReadEngine, nativeLibraries?: (() => Promise<readonly Record<string, unknown>[]>) | undefined);
     /** Confirm the engine can read one project. */
     workflow(project: ProjectRef): Promise<EngineResult>;
     /**

package/vendor/mwi/lib/read/service.js

@@ -15,11 +15,18 @@ export const GET_KINDS = ['pou', 'type', 'task', 'block', 'eip'];
 /** The saved-project read service. */
 export class ReadService {
     engine;
+    nativeLibraries;
     /**
      * @param engine - Code engine over the project files.
+     * @param nativeLibraries - Live IDE library inventory, when the host has one.
+     *   A block interface is decoded against the installed libraries as well as the
+     *   saved project, so without it a vendor block cannot be resolved. Reads stay
+     *   usable without an IDE: the provider returns nothing and the engine answers
+     *   for the project's own registry alone.
      */
-    constructor(engine) {
+    constructor(engine, nativeLibraries) {
         this.engine = engine;
+        this.nativeLibraries = nativeLibraries;
     }
     /** Confirm the engine can read one project. */
     async workflow(project) {
@@ -62,9 +69,14 @@ export class ReadService {
             return { ...text, project: project.directory, ...digest };
         }
         if (kind === 'block') {
+            // The engine compares the saved library references with the installed
+            // inventory, so a missing inventory is a refusal, not a crash: pass what the
+            // host could observe (nothing when the IDE is closed).
+            const native = this.nativeLibraries === undefined ? [] : await this.nativeLibraries().catch(() => []);
             return await this.engine.run('block_interface', {
                 project: project.directory,
                 name,
+                native_libraries: native,
                 ...(library === undefined ? {} : { library }),
             }, 60_000);
         }

package/vendor/mwi/lib/session/service.js

@@ -102,7 +102,13 @@ export class PowerShellSessionRuntime {
         }));
         this.engine = new CodeEngine({ workspace, stageRoot: stageRootOf(workspace), codeDir: CODE_DIR });
         this.stages = new StageService(this.engine, workspace);
-        this.reads = new ReadService(this.engine);
+        // A block interface is decoded against the installed libraries as well as the
+        // saved project. That inventory is a live IDE read; when no IDE answers, the
+        // read service falls back to the project's own registry instead of failing.
+        this.reads = new ReadService(this.engine, async () => {
+            const snapshot = await this.bridge.run('library_snapshot', {}, 30_000);
+            return (snapshot.libraries ?? []).map(row => ({ name: String(row.name ?? ''), full_name: String(row.full_name ?? '') }));
+        });
     }
     /** @returns The bridge's status document. */
     async status() {