node-opcua-address-space 2.181.1 → 2.182.2

package/api/helpers/ensure_secure_access.ts

@@ -1,6 +1,13 @@
 import type { BaseNode, IChannelBase, UAMethod, UAObject, UAVariable } from "node-opcua-address-space-base";
-import { allPermissions, BrowseDirection, makeAccessRestrictionsFlag, makePermissionFlag, NodeClass } from "node-opcua-data-model";
-import { MessageSecurityMode } from "node-opcua-types";
+import {
+    allPermissions,
+    BrowseDirection,
+    makeAccessRestrictionsFlag,
+    makePermissionFlag,
+    NodeClass,
+    PermissionFlag
+} from "node-opcua-data-model";
+import { MessageSecurityMode, type RolePermissionType } from "node-opcua-types";
 import { WellKnownRoles } from "../session_context.js";
 
 function _isChannelSecure(channel: IChannelBase): boolean {
@@ -76,3 +83,47 @@ export function ensureObjectIsSecure(node: BaseNode, options: EnsureObjectIsSecu
         ensureObjectIsSecure(child, options);
     }
 }
+
+/** the two Roles every Session's permissions are evaluated against, granted Browse and nothing else */
+const browseForEverySession = [
+    { roleId: WellKnownRoles.Anonymous, permissions: makePermissionFlag("Browse") },
+    { roleId: WellKnownRoles.AuthenticatedUser, permissions: makePermissionFlag("Browse") }
+];
+
+function grantsBrowseToEverySession(rolePermissions: RolePermissionType[]): boolean {
+    return rolePermissions.some(
+        ({ roleId, permissions }) =>
+            (permissions & PermissionFlag.Browse) !== 0 &&
+            roleId.namespace === 0 &&
+            (roleId.value === WellKnownRoles.Anonymous || roleId.value === WellKnownRoles.AuthenticatedUser)
+    );
+}
+
+/**
+ * keep the structure of `node` and its aggregates browsable by every session, leaving every
+ * other permission as declared.
+ *
+ * A node whose RolePermissions grant Browse to neither Anonymous nor AuthenticatedUser is
+ * hidden from any session that holds none of the roles it names. Where those roles are ones
+ * the server never assigns, nobody sees the node, and its parent - browsable by everyone -
+ * shows an instance missing the mandatory children of its type. `Opc.Ua.NodeSet2.xml` does
+ * this to eleven nodes under Server/PublishSubscribe (the methods of SecurityGroups and
+ * KeyPushTargets, with their arguments), reserved to the SecurityKeyServerAdmin role
+ * (CTT Base Info Core Structure 002, FEAT-30).
+ *
+ * Such a node gains Browse for Anonymous and AuthenticatedUser, which every session's
+ * permissions are evaluated against; Read, Write and Call stay with the roles it named. A
+ * node without RolePermissions, or that already grants Browse to one of the two, is left as
+ * it is.
+ *
+ * @param node the node whose structure, and whose aggregates' structure, must stay visible
+ */
+export function ensureStructureIsBrowsable(node: BaseNode): void {
+    const rolePermissions = node.rolePermissions;
+    if (rolePermissions && !grantsBrowseToEverySession(rolePermissions)) {
+        node.setRolePermissions([...rolePermissions, ...browseForEverySession]);
+    }
+    for (const child of node.findReferencesExAsObject("Aggregates", BrowseDirection.Forward)) {
+        ensureStructureIsBrowsable(child);
+    }
+}

package/api/index.ts

@@ -156,7 +156,26 @@ export * from "./interfaces/state_machine/ua_transition_ex.js";
 export * from "./interfaces/ua_subscription_diagnostics_variable_ex.js";
 export { ensureDatatypeExtracted, ensureDatatypeExtractedWithCallback } from "./loader/ensure_datatype_extracted.js";
 export * from "./loader/generateAddressSpaceRaw.js";
+export { type NarrowedDataType, narrowInstanceDataTypes } from "./loader/narrow_instance_datatypes.js";
 export {
+    isNdjsonHeaderLine,
+    NDJSON_IMAGE_FORMAT,
+    NODESET2_XML_FORMAT,
+    registerBuiltinNodesetFormats
+} from "./loader/nodeset_builtin_formats.js";
+export {
+    findNodesetFormat,
+    type NodesetDocument,
+    type NodesetFormat,
+    type NodesetHead,
+    type NodesetModel,
+    type NodesetModelInfo,
+    nodesetFormatByName,
+    nodesetFormats,
+    registerNodesetFormat
+} from "./loader/nodeset_format.js";
+export {
+    type ImageDeflater,
     imageLinesToRecords,
     imageNodesetRecords,
     inflatedImageLines,
@@ -169,6 +188,7 @@ export {
     nodesetImageProblem,
     type ReadNodesetImageOptions,
     readNodesetImageInfo,
+    setImageDeflater,
     setImageInflater
 } from "./loader/nodeset_image.js";
 export { decodeValue, encodeValue, type JsonNodeId, type JsonQualifiedName, type JsonValue } from "./loader/nodeset_image_codec.js";
@@ -193,10 +213,19 @@ export {
     recordBytes,
     XmlExtensionObjectFragment
 } from "./loader/nodeset_record.js";
-export type { NamedNodesetSource, NodesetChunk, NodesetChunkStream, NodesetSource } from "./loader/nodeset_source.js";
+export { type RecordsToNodeset2XMLOptions, recordsToNodeset2XML } from "./loader/nodeset_records_to_xml.js";
+export type {
+    NamedNodesetSource,
+    NodesetChunk,
+    NodesetChunkStream,
+    NodesetContainer,
+    NodesetSource,
+    NodesetSourceKind
+} from "./loader/nodeset_source.js";
 export { sha256Hex } from "./loader/nodeset_source.js";
 export * from "./loader/nodeset_source_helpers.js";
 export { type NodesetToImageOptions, nodesetToImage } from "./loader/nodeset_to_image.js";
+export { headerComplete, parseDependencies, sliceHeader } from "./loader/nodeset_xml_header.js";
 export { makeXmlNodesetRecordReader, type XmlNodesetRecordReader, xmlNodesetRecords } from "./loader/nodeset_xml_producer.js";
 export * from "./loader/register_node_promoter.js";
 export * from "./namespace.js";

package/api/loader/generateAddressSpaceRaw.ts

@@ -1,14 +1,20 @@
 import type { IAddressSpace, RequiredModel } from "node-opcua-address-space-base";
-import { getMinOPCUADate } from "node-opcua-date-time";
 import { checkDebugFlag, make_debugLog, make_errorLog } from "node-opcua-debug";
 import type { CallbackT } from "node-opcua-status-code";
-import { type ReaderStateParser, type ReaderStateParserLike, Xml2Json, type XmlAttributes } from "node-opcua-xml2json";
 import semver from "semver";
 import type { NamespacePrivate } from "../../impl/namespace_private.js";
 import { adjustNamespaceArray } from "../../impl/nodeset_tools/adjust_namespace_array.js";
 import type { NodeSetLoaderOptions } from "../interfaces/nodeset_loader_options.js";
 import { NodeSetLoader } from "./load_nodeset2.js";
 import { makeSemverCompatible } from "./make_semver_compatible.js";
+import { NDJSON_IMAGE_FORMAT, registerBuiltinNodesetFormats } from "./nodeset_builtin_formats.js";
+import {
+    type NodesetModel as Model,
+    type NodesetDocument,
+    type NodesetFormat,
+    type NodesetModelInfo as NodesetInfo,
+    nodesetFormatByName
+} from "./nodeset_format.js";
 import {
     imageLinesToRecords,
     inflatedImageLines,
@@ -21,92 +27,17 @@ import {
 import { decodeHeader } from "./nodeset_image_codec.js";
 import { type NodesetImageStore, nodesetImageKey, sharedMemoryNodesetImageStore } from "./nodeset_image_store.js";
 import type { NodesetRecord, NodesetRecordConsumer } from "./nodeset_record.js";
-import { type NodesetReader, type NodesetSource, openNodesetSource } from "./nodeset_source.js";
-import { xmlNodesetRecords } from "./nodeset_xml_producer.js";
+import { type NodesetReader, type NodesetSource, nodesetDocumentOf, openNodesetSource } from "./nodeset_source.js";
+import { parseDependencies, sliceHeader } from "./nodeset_xml_header.js";
+
+// the loader reads NodeSet2 XML and its own NDJSON images out of the box: registering them is
+// what makes that true, and it has to happen before any source is sniffed
+registerBuiltinNodesetFormats();
 
 const doDebug = checkDebugFlag("generateAddressSpaceRaw");
 const debugLog = make_debugLog("generateAddressSpaceRaw");
 const errorLog = make_errorLog("generateAddressSpaceRaw");
 
-interface Model extends RequiredModel {
-    requiredModel: RequiredModel[];
-}
-interface NodesetInfo {
-    namespaceUris: string[];
-    models: Model[];
-}
-
-async function parseDependencies(xmlData: string): Promise<NodesetInfo> {
-    const namespaceUris: string[] = [];
-
-    const models: Model[] = [];
-    let currentModel: Model | undefined;
-    const state0: ReaderStateParser = {
-        parser: {
-            UANodeSet: {
-                parser: {
-                    NamespaceUris: {
-                        parser: {
-                            Uri: <ReaderStateParserLike & { text: string }>{
-                                finish(this: ReaderStateParserLike & { text: string }) {
-                                    namespaceUris.push(this.text);
-                                }
-                            }
-                        }
-                    },
-                    Models: {
-                        parser: {
-                            Model: {
-                                init(_elementName: string, attrs: XmlAttributes) {
-                                    const modelUri = attrs.ModelUri;
-                                    const version = attrs.Version;
-                                    const publicationDate = new Date(Date.parse(attrs.PublicationDate));
-                                    currentModel = {
-                                        modelUri,
-                                        version,
-                                        publicationDate,
-                                        requiredModel: []
-                                    };
-                                    doDebug && console.log(`currentModel = ${JSON.stringify(currentModel)}`);
-                                    models.push(currentModel);
-                                },
-                                parser: {
-                                    RequiredModel: {
-                                        init(_elementName: string, attrs: XmlAttributes) {
-                                            const modelUri = attrs.ModelUri;
-                                            const version = attrs.Version;
-                                            const publicationDate = new Date(Date.parse(attrs.PublicationDate));
-
-                                            if (!currentModel) {
-                                                throw new Error("Internal Error");
-                                            }
-                                            currentModel.requiredModel.push({
-                                                modelUri,
-                                                version,
-                                                publicationDate
-                                            });
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        }
-    };
-    const parser = new Xml2Json(state0);
-    parser.parseString(xmlData);
-    if (models.length === 0 && namespaceUris.length >= 1) {
-        models.push({
-            modelUri: namespaceUris[0],
-            version: "1",
-            publicationDate: getMinOPCUADate(),
-            requiredModel: []
-        });
-    }
-    return { models, namespaceUris: namespaceUris };
-}
 interface NodesetDesc {
     index: number;
     xmlData: string;
@@ -116,30 +47,10 @@ interface NodesetSourceDesc {
     index: number;
     reader: NodesetReader;
     namespaceModel: NodesetInfo;
-    /** the bytes of a source that holds an image, read whole */
-    image?: Uint8Array;
-}
-
-/**
- * the header of a NodeSet2 file (`NamespaceUris`, `Models`) precedes the aliases and the nodes: the
- * dependency pre-pass has read enough once both closers were seen, or once the body has begun
- */
-const BODY_START =
-    /<(Aliases|Extensions|UAObject|UAVariable|UADataType|UAReferenceType|UAObjectType|UAVariableType|UAMethod|UAView)[\s/>]/;
-function headerComplete(text: string): boolean {
-    return (text.includes("</Models>") && text.includes("</NamespaceUris>")) || BODY_START.test(text);
-}
-
-/** the `<UANodeSet ...>` opener up to the end of `</Models>` or `</NamespaceUris>`, whichever comes last */
-function sliceHeader(xmlData: string, name: string): string {
-    const indexStart = xmlData.match(/<UANodeSet/m)?.index;
-    const i1 = (xmlData.match(/<\/Models>/m)?.index || 0) + "</Models>".length;
-    const i2 = (xmlData.match(/<\/NamespaceUris>/m)?.index || 0) + "</NamespaceUris>".length;
-    const indexEnd = Math.max(i1, i2);
-    if (indexStart === undefined) {
-        throw new Error(`nodeset source ${name}: no <UANodeSet> element found`);
-    }
-    return xmlData.substring(indexStart, indexEnd);
+    /** the format that claimed this source */
+    format: NodesetFormat;
+    /** the source seen as a document, so the read and the inflate are shared with the pre-pass */
+    document: NodesetDocument;
 }
 
 /**
@@ -150,30 +61,15 @@ async function preLoadSources(readers: NodesetReader[]): Promise<NodesetSourceDe
     for (let index = 0; index < readers.length; index++) {
         const reader = readers[index];
         doDebug && console.log("---------------------------------------------", reader.name);
-        if ((await reader.probe()) === "image") {
-            // an image is small (a few hundred KB) and its header is line 1: read it whole
-            const image = await reader.allBytes();
-            const { header } = await readNodesetImageInfo(image);
-            const models: Model[] = header.models.map((m) => ({
-                modelUri: m.modelUri,
-                version: m.version,
-                publicationDate: m.publicationDate ? new Date(m.publicationDate) : getMinOPCUADate(),
-                requiredModel: m.requiredModels.map((r) => ({ ...r, publicationDate: new Date(r.publicationDate ?? Number.NaN) }))
-            }));
-            if (models.length === 0 && header.namespaceUris.length >= 1) {
-                models.push({
-                    modelUri: header.namespaceUris[0],
-                    version: "1",
-                    publicationDate: getMinOPCUADate(),
-                    requiredModel: []
-                });
-            }
-            namespaceDesc.push({ reader, namespaceModel: { models, namespaceUris: header.namespaceUris }, index, image });
-            continue;
+        const format = nodesetFormatByName(await reader.probe());
+        // probe() only returns a name it found in the registry, so this cannot be missing; the
+        // check is here because a caller may unregister a format between the probe and the load
+        if (!format) {
+            throw new Error(`nodeset source ${reader.name}: its format is no longer registered`);
         }
-        const head = await reader.readHead(headerComplete);
-        const namespaceModel = await parseDependencies(sliceHeader(head, reader.name));
-        namespaceDesc.push({ reader, namespaceModel, index });
+        const document = nodesetDocumentOf(reader);
+        const namespaceModel = await format.readModels(document);
+        namespaceDesc.push({ reader, document, format, namespaceModel, index });
     }
     return namespaceDesc;
 }
@@ -217,16 +113,23 @@ async function isReplayable(image: Uint8Array, digest: string, name: string): Pr
 }
 
 /**
- * load one XML source: from its image when the store holds a valid one, from the XML otherwise,
- * writing the image on the way when there is a store
+ * load one source through the image cache: from its image when the store holds a valid one, by
+ * parsing it otherwise, writing the image on the way when there is a store.
+ *
+ * This used to be the XML path, because XML was the only thing worth caching a parse of. It is
+ * now every format except the image itself: the cache is keyed on the digest of the bytes that
+ * were read, and nothing about that reasoning was ever specific to XML. A published nodeset in
+ * any format therefore gets a cache sibling on first read and loads at image speed after it.
  */
-async function loadXmlSource(
+async function loadThroughCache(
     nodesetLoader: NodeSetLoader,
+    format: NodesetFormat,
+    document: NodesetDocument,
     reader: NodesetReader,
     store: NodesetImageStore | undefined
 ): Promise<void> {
     if (!store) {
-        await nodesetLoader.addNodeSetStream(reader.chunks());
+        await nodesetLoader.addRecords(format.records(document));
         return;
     }
     // the digest is known up front for a document given whole; a stream must be read first
@@ -247,7 +150,7 @@ async function loadXmlSource(
         }
     }
     const writer = new NodesetImageWriter();
-    await nodesetLoader.addRecords(tee(xmlNodesetRecords(reader.chunks()), writer));
+    await nodesetLoader.addRecords(tee(format.records(document), writer));
     const sourceDigest = digest ?? (await reader.digest());
     try {
         await store.put(nodesetImageKey(sourceDigest), await writer.finish(sourceDigest, reader.length));
@@ -444,14 +347,16 @@ export async function generateAddressSpaceRaw(
         // c8 ignore next
         doDebug && debugLog(" loading ", nodesetIndex, nodeset.reader.name);
         try {
-            if (nodeset.image) {
+            if (nodeset.format.name === NDJSON_IMAGE_FORMAT) {
+                // an image is already the cache: replaying it through the cache would be storing
+                // a copy of what was just read
                 try {
-                    await nodesetLoader.addRecords(imageLinesToRecords(await inflatedImageLines(nodeset.image)));
+                    await nodesetLoader.addRecords(nodeset.format.records(nodeset.document));
                 } finally {
-                    releaseInflatedImageLines(nodeset.image);
+                    releaseInflatedImageLines(await nodeset.document.rawBytes());
                 }
             } else {
-                await loadXmlSource(nodesetLoader, nodeset.reader, store);
+                await loadThroughCache(nodesetLoader, nodeset.format, nodeset.document, nodeset.reader, store);
             }
         } catch (err) {
             const cause = err instanceof Error ? err.message : String(err);

package/api/loader/load_nodeset2.ts

@@ -15,6 +15,7 @@ import type { NamespacePrivate } from "../../impl/namespace_private.js";
 import type { NodeSetLoaderOptions } from "../interfaces/nodeset_loader_options.js";
 import { ensureDatatypeExtracted } from "./ensure_datatype_extracted.js";
 import { promoteObjectsAndVariables } from "./namespace_post_step.js";
+import { narrowInstanceDataTypes } from "./narrow_instance_datatypes.js";
 import { type NodesetRecord, type NodesetRecordProducer, type NodesetRecordWithBytes, recordBytes } from "./nodeset_record.js";
 import type { PendingBackReferences } from "./nodeset_record_applier.js";
 import { type LoaderTaskQueues, makeLoaderTaskQueues, NodesetRecordApplier, type Task } from "./nodeset_record_applier.js";
@@ -257,6 +258,10 @@ export class NodeSetLoader {
                 queues.postTasks2_AssignedExtensionObjectToDataValue
             );
 
+            doDebug && debugLog(chalk.bgGreenBright("Narrowing instance DataTypes to their declaration ---------------------"));
+            // after the values are in: a value that would not fit the declared type keeps the variable as it is
+            narrowInstanceDataTypes(addressSpace1);
+
             doDebug && debugLog(chalk.bgGreenBright("Performing post variable initialization ---------------------"));
             // awaited: a promoter that throws must reject generateAddressSpace, not surface later
             // as an unhandled rejection once the caller believes the address space is complete

package/api/loader/narrow_instance_datatypes.ts

@@ -0,0 +1,264 @@
+/**
+ * @module node-opcua-address-space
+ */
+import type {
+    BaseNode,
+    IAddressSpace,
+    UADataType,
+    UAObject,
+    UAObjectType,
+    UAReferenceType,
+    UAVariable,
+    UAVariableType
+} from "node-opcua-address-space-base";
+import { BrowseDirection, NodeClass, type QualifiedName } from "node-opcua-data-model";
+import { checkDebugFlag, make_debugLog } from "node-opcua-debug";
+import { type NodeId, sameNodeId } from "node-opcua-nodeid";
+import { DataType } from "node-opcua-variant";
+import type { NamespacePrivate } from "../../impl/namespace_private.js";
+
+const doDebug = checkDebugFlag("narrow_instance_datatypes");
+const debugLog = make_debugLog("narrow_instance_datatypes");
+
+type UAType = UAObjectType | UAVariableType;
+type UAInstance = UAObject | UAVariable;
+
+function isType(node: BaseNode): node is UAType {
+    return node.nodeClass === NodeClass.ObjectType || node.nodeClass === NodeClass.VariableType;
+}
+function isInstance(node: BaseNode): node is UAInstance {
+    return node.nodeClass === NodeClass.Object || node.nodeClass === NodeClass.Variable;
+}
+
+/**
+ * the type definition of an instance, resolved without the ObjectType/VariableType guards of the
+ * typed getters: a companion nodeset with a wrong type definition must not abort the sweep
+ */
+function typeDefinitionOf(addressSpace: IAddressSpace, node: UAInstance): UAType | null {
+    const typeDefinition: NodeId | undefined = node.typeDefinition;
+    if (!typeDefinition || typeDefinition.isEmpty()) {
+        return null;
+    }
+    const typeNode = addressSpace.findNode(typeDefinition);
+    return typeNode && isType(typeNode) ? typeNode : null;
+}
+
+/**
+ * the members a type declares, by browse name, looked up along its supertype chain and its
+ * interfaces the way `instantiate` collects them (see impl/_instantiate_helpers.ts); the answer
+ * is cached per (type, browse name) so a sweep over thousands of instances of the same type
+ * walks the chain once per member
+ */
+class DeclarationIndex {
+    private readonly cache = new Map<string, BaseNode | null>();
+    /** absent from a standard nodeset older than 1.04: then no type has interfaces to look into */
+    private readonly hasInterface: UAReferenceType | null;
+    private readonly hasModellingRule: UAReferenceType;
+
+    constructor(
+        private readonly addressSpace: IAddressSpace,
+        hasModellingRule: UAReferenceType
+    ) {
+        this.hasInterface = addressSpace.findReferenceType("HasInterface") ?? null;
+        this.hasModellingRule = hasModellingRule;
+    }
+
+    /**
+     * whether `declared` is a member declaration a variable instance must honour: a variable with
+     * a modelling rule (Mandatory, Optional, ...). A type child without one is not instantiated by
+     * Part 3 and is left alone.
+     */
+    public isVariableDeclaration(declared: BaseNode): declared is UAVariable {
+        return (
+            declared.nodeClass === NodeClass.Variable &&
+            declared.findReferencesEx(this.hasModellingRule, BrowseDirection.Forward).length > 0
+        );
+    }
+
+    public find(type: UAType, browseName: QualifiedName): BaseNode | null {
+        const key = `${type.nodeId.toString()}|${browseName.toString()}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const found = this.walk(type, browseName, new Set<string>());
+        this.cache.set(key, found);
+        return found;
+    }
+
+    private walk(type: UAType, browseName: QualifiedName, visited: Set<string>): BaseNode | null {
+        const typeKey = type.nodeId.toString();
+        if (visited.has(typeKey)) {
+            return null;
+        }
+        visited.add(typeKey);
+        const child = type.getChildByName(browseName);
+        if (child) {
+            return child;
+        }
+        const interfaces = this.hasInterface ? type.findReferencesEx(this.hasInterface, BrowseDirection.Forward) : [];
+        for (const reference of interfaces) {
+            const interfaceType = reference.node ?? this.addressSpace.findNode(reference.nodeId);
+            if (interfaceType && isType(interfaceType)) {
+                const declared = this.walk(interfaceType, browseName, visited);
+                if (declared) {
+                    return declared;
+                }
+            }
+        }
+        const superType = type.subtypeOfObj as UAType | null;
+        return superType ? this.walk(superType, browseName, visited) : null;
+    }
+}
+
+// a parent chain deeper than this is a cycle in a broken nodeset, not a model
+const MAX_DEPTH = 64;
+
+/**
+ * the node of a type definition that declares this instance member, or null when no type in
+ * the instance's ancestry declares one under its browse name.
+ *
+ * The declaration is looked up in the type definition of the containing instance first; a
+ * member nested below a declared member (an object declared by the type with children of its
+ * own, whose own type definition says nothing about them) is found through the declaration of
+ * its container instead.
+ */
+function declarationOf(addressSpace: IAddressSpace, index: DeclarationIndex, node: UAInstance, depth: number): BaseNode | null {
+    if (depth > MAX_DEPTH) {
+        return null;
+    }
+    const parent = node.parent;
+    // a node under a type is a declaration itself, never an instance to narrow
+    if (!parent || isType(parent)) {
+        return null;
+    }
+    const parentIsInstance = isInstance(parent);
+    if (parentIsInstance) {
+        const parentType = typeDefinitionOf(addressSpace, parent);
+        if (parentType) {
+            const declared = index.find(parentType, node.browseName);
+            if (declared) {
+                return declared;
+            }
+        }
+    }
+    // the container may itself be a declared member (an instance, or a method) whose declaration
+    // carries the member; a method has no type definition and is resolved the same way
+    if (parentIsInstance || parent.nodeClass === NodeClass.Method) {
+        const parentDeclaration = declarationOf(addressSpace, index, parent as UAInstance, depth + 1);
+        if (parentDeclaration) {
+            return parentDeclaration.getChildByName(node.browseName);
+        }
+    }
+    return null;
+}
+
+function findDataTypeNode(addressSpace: IAddressSpace, nodeId: NodeId): UADataType | null {
+    if (!nodeId || nodeId.isEmpty()) {
+        return null;
+    }
+    return addressSpace.findDataType(nodeId) ?? null;
+}
+
+/** where a variable keeps the built-in type it derived from its DataType (see impl/get_basic_datatype.ts) */
+interface VariableWithBasicDataTypeCache {
+    _basicDataType?: DataType | null;
+}
+
+export interface NarrowedDataType {
+    node: UAVariable;
+    from: NodeId;
+    to: NodeId;
+}
+
+/**
+ * make every instance variable's DataType at least as narrow as its declaration.
+ *
+ * OPC 10000-3 lets an instance use the DataType its type definition declares for the member, or
+ * a subtype of it; a supertype is not conformant. Companion nodesets that predate a narrowing
+ * of the standard types carry the supertype anyway (every NamespaceMetadata object written
+ * against UA 1.04 declares `ModelVersion` as String, which UA 1.05 narrowed to
+ * SemanticVersionString), so every server loading them fails the type-conformance check of
+ * the CTT (Base Info Core Structure) and no server can fix it per nodeset. The declared type is
+ * what the model means: an instance whose DataType is a strict supertype of the declared one is
+ * moved to the declared one.
+ *
+ * Nothing else moves: an instance whose DataType is the declared one, a subtype of it, or
+ * unrelated is left alone, values are never touched, and the children of types are declarations,
+ * not instances. A variable whose current value would not fit the declared built-in type is
+ * left alone as well, and reported: narrowing it would make the value lie about its type.
+ *
+ * @returns the variables that were narrowed
+ */
+export function narrowInstanceDataTypes(addressSpace: IAddressSpace): NarrowedDataType[] {
+    const narrowed: NarrowedDataType[] = [];
+    // a nodeset without these cannot declare a member, let alone the DataType of one: a
+    // minimal fixture, or a standard nodeset still to come. Nothing to narrow, and the lookups
+    // below would throw on the first missing reference type.
+    const hasModellingRule = addressSpace.findReferenceType("HasModellingRule");
+    if (
+        !hasModellingRule ||
+        !addressSpace.findReferenceType("HasSubtype") ||
+        !addressSpace.findReferenceType("HasChild") ||
+        !addressSpace.findReferenceType("HierarchicalReferences")
+    ) {
+        return narrowed;
+    }
+    const index = new DeclarationIndex(addressSpace, hasModellingRule);
+
+    for (const namespace of addressSpace.getNamespaceArray()) {
+        for (const node of (namespace as NamespacePrivate).nodeIterator()) {
+            if (node.nodeClass !== NodeClass.Variable) {
+                continue;
+            }
+            const variable = node as UAVariable;
+            const declared = declarationOf(addressSpace, index, variable, 0);
+            if (!declared || !index.isVariableDeclaration(declared)) {
+                continue;
+            }
+            if (sameNodeId(variable.dataType, declared.dataType)) {
+                continue;
+            }
+            const instanceDataType = findDataTypeNode(addressSpace, variable.dataType);
+            const declaredDataType = findDataTypeNode(addressSpace, declared.dataType);
+            if (!instanceDataType || !declaredDataType) {
+                continue;
+            }
+            // a subtype of the declaration, or an unrelated type: not this sweep's business
+            if (!declaredDataType.isSubtypeOf(instanceDataType)) {
+                continue;
+            }
+            const value = variable.readValue().value;
+            const declaredBuiltInType = declaredDataType.basicDataType;
+            const valueFits =
+                value.dataType === DataType.Null ||
+                declaredBuiltInType === DataType.Variant ||
+                value.dataType === declaredBuiltInType;
+            if (!valueFits) {
+                debugLog(
+                    `not narrowing ${variable.nodeId.toString()} ${variable.browseName.toString()}: ` +
+                        `its value is a ${DataType[value.dataType]}, the declared ${declaredDataType.browseName.toString()} ` +
+                        `is a ${DataType[declaredBuiltInType]}`
+                );
+                continue;
+            }
+            const from = variable.dataType;
+            variable.dataType = declaredDataType.nodeId;
+            (variable as unknown as VariableWithBasicDataTypeCache)._basicDataType = null;
+            narrowed.push({ node: variable, from, to: declaredDataType.nodeId });
+            // c8 ignore next
+            if (doDebug) {
+                debugLog(
+                    `narrowed the DataType of ${variable.nodeId.toString()} ${variable.browseName.toString()} ` +
+                        `from ${instanceDataType.browseName.toString()} (${from.toString()}) ` +
+                        `to the declared ${declaredDataType.browseName.toString()} (${declaredDataType.nodeId.toString()})`
+                );
+            }
+        }
+    }
+    // c8 ignore next
+    if (doDebug && narrowed.length > 0) {
+        debugLog(`narrowed the DataType of ${narrowed.length} instance variable(s) to the one their type declares`);
+    }
+    return narrowed;
+}