node-opcua-alias-name-server 2.176.0

package/dist/alias_index.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * A per-category index from AliasName to the `AliasNameType` Object that carries
+ * it.
+ *
+ * ## Why this exists
+ *
+ * Looking an alias up by name means finding a child of the category with a given
+ * BrowseName. The address space has an O(1) index for exactly that — but
+ * `getChildByName` only consults it for `HasChild` subtypes, and an alias is an
+ * `Organizes` child of its category (clause 6.3 Table 2). `getFolderElementByName`
+ * does cover `Organizes`, but scans. So neither route is both correct and fast.
+ *
+ * That matters because `addAlias` has to look for an existing alias of the same
+ * name before creating one, so a Server building N aliases performed N linear
+ * scans of a growing category — quadratic. Measured on a category holding 1500
+ * aliases, 200 lookups cost 97 ms by scanning and 0 ms through this index, and
+ * building 1500 aliases went from 2545 ms to 1686 ms.
+ *
+ * That is not the whole story: the larger remaining cost is inside
+ * `UAObjectType.instantiate`, which is itself superlinear in the number of
+ * children the parent already has. That is an address-space concern rather than
+ * an AliasName one, and is tracked separately.
+ *
+ * ## How it stays correct
+ *
+ * The index is built lazily, from one full scan, so aliases modelled in a
+ * NodeSet2.xml are picked up. After that it is maintained incrementally by
+ * {@link noteAliasAdded} and {@link noteAliasRemoved}, which `addAlias` and
+ * `removeAlias` call.
+ *
+ * A hit is verified against the address space before being returned, so an alias
+ * deleted by other means degrades to a miss rather than a dangling Object. A
+ * miss is trusted: an alias created behind this package's back after the index
+ * was built would not be found, and `addAlias` would then fail loudly on the
+ * duplicate BrowseName rather than corrupting anything. Call
+ * {@link invalidateAliasIndex} if a Server mutates a category by other means.
+ *
+ * Keyed by the node itself in a `WeakMap`, so a disposed address space takes its
+ * indexes with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupAlias = lookupAlias;
+exports.noteAliasAdded = noteAliasAdded;
+exports.noteAliasRemoved = noteAliasRemoved;
+exports.invalidateAliasIndex = invalidateAliasIndex;
+const node_opcua_data_model_1 = require("node-opcua-data-model");
+const alias_hierarchy_js_1 = require("./alias_hierarchy.js");
+const indexes = new WeakMap();
+/** Build the index for a category by scanning it once. */
+function buildIndex(addressSpace, category) {
+    const index = new Map();
+    const aliasNameType = (0, alias_hierarchy_js_1.findAliasNameType)(addressSpace);
+    if (!aliasNameType) {
+        return index;
+    }
+    for (const child of category.findReferencesExAsObject("HierarchicalReferences", node_opcua_data_model_1.BrowseDirection.Forward)) {
+        if (child.nodeClass !== node_opcua_data_model_1.NodeClass.Object) {
+            continue;
+        }
+        const name = child.browseName.name;
+        if (!name || index.has(name)) {
+            continue;
+        }
+        const typeDefinition = child.typeDefinitionObj;
+        if (typeDefinition &&
+            (typeDefinition.nodeId.value === aliasNameType.nodeId.value || typeDefinition.isSubtypeOf(aliasNameType))) {
+            index.set(name, child.nodeId);
+        }
+    }
+    return index;
+}
+/** The index for a category, built on first use. */
+function indexOf(addressSpace, category) {
+    let index = indexes.get(category);
+    if (!index) {
+        index = buildIndex(addressSpace, category);
+        indexes.set(category, index);
+    }
+    return index;
+}
+/**
+ * The `AliasNameType` instance with this name in `category`, or null.
+ *
+ * O(1) after the first call on a given category.
+ */
+function lookupAlias(addressSpace, category, aliasName) {
+    const index = indexOf(addressSpace, category);
+    const nodeId = index.get(aliasName);
+    if (!nodeId) {
+        return null;
+    }
+    const node = addressSpace.findNode(nodeId);
+    if (!node || node.nodeClass !== node_opcua_data_model_1.NodeClass.Object) {
+        // deleted behind our back; forget it rather than hand back a ghost
+        index.delete(aliasName);
+        return null;
+    }
+    return node;
+}
+/** Record a newly created alias. */
+function noteAliasAdded(addressSpace, category, aliasName, nodeId) {
+    indexOf(addressSpace, category).set(aliasName, nodeId);
+}
+/** Record a removed alias. */
+function noteAliasRemoved(addressSpace, category, aliasName) {
+    indexOf(addressSpace, category).delete(aliasName);
+}
+/**
+ * Forget a category's index, so it is rebuilt from the address space on next
+ * use. Needed only if a Server adds or removes aliases without going through
+ * {@link addAlias} / {@link removeAlias}.
+ */
+function invalidateAliasIndex(category) {
+    indexes.delete(category);
+}
+//# sourceMappingURL=alias_index.js.map

package/dist/alias_index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias_index.js","sourceRoot":"","sources":["../source/alias_index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;;AAqDH,kCAaC;AAGD,wCAEC;AAGD,4CAEC;AAOD,oDAEC;AAlFD,iEAAmE;AAEnE,6DAAyD;AAKzD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAwB,CAAC;AAEpD,0DAA0D;AAC1D,SAAS,UAAU,CAAC,YAA2B,EAAE,QAAkB;IAC/D,MAAM,KAAK,GAAe,IAAI,GAAG,EAAE,CAAC;IACpC,MAAM,aAAa,GAAG,IAAA,sCAAiB,EAAC,YAAY,CAAC,CAAC;IACtD,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,wBAAwB,CAAC,wBAAwB,EAAE,uCAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QACvG,IAAI,KAAK,CAAC,SAAS,KAAK,iCAAS,CAAC,MAAM,EAAE,CAAC;YACvC,SAAS;QACb,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QACnC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,SAAS;QACb,CAAC;QACD,MAAM,cAAc,GAAI,KAAkB,CAAC,iBAAiB,CAAC;QAC7D,IACI,cAAc;YACd,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,KAAK,aAAa,CAAC,MAAM,CAAC,KAAK,IAAI,cAAc,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,EAC3G,CAAC;YACC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,oDAAoD;AACpD,SAAS,OAAO,CAAC,YAA2B,EAAE,QAAkB;IAC5D,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,KAAK,GAAG,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,YAA2B,EAAE,QAAkB,EAAE,SAAiB;IAC1F,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,KAAK,iCAAS,CAAC,MAAM,EAAE,CAAC;QAC/C,mEAAmE;QACnE,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,IAAgB,CAAC;AAC5B,CAAC;AAED,oCAAoC;AACpC,SAAgB,cAAc,CAAC,YAA2B,EAAE,QAAkB,EAAE,SAAiB,EAAE,MAAc;IAC7G,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,8BAA8B;AAC9B,SAAgB,gBAAgB,CAAC,YAA2B,EAAE,QAAkB,EAAE,SAAiB;IAC/F,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,QAAkB;IACnD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC"}

package/dist/alias_name_archive.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Persistence for `LastChange` (OPC 10000-17 clause 6.3.1).
+ *
+ * Clause 6.3.1 is blunt about why this exists: *"The LastChange shall be
+ * persisted. A Client that detects a LastChange that is older than what it has
+ * cached, shall clear all cached AliasNameCategories and related AliasNames."*
+ *
+ * So a restart that reset `LastChange` to zero would not merely lose
+ * information — it would order every connected Client to throw away a cache
+ * that is still perfectly valid, silently and on every restart. That is a
+ * Server-side bug whose only symptom is remote.
+ *
+ * The archive is plain JSON: a version and a map of category NodeId to
+ * VersionTime. There is nothing secret in it, so unlike the RoleSet archive it
+ * is not encrypted — it is a handful of integers describing when things last
+ * changed. Writes are atomic (temp file + rename) so a crash cannot leave a
+ * half-written archive, which would be worse than no archive at all.
+ */
+/** Bumped when the on-disk shape changes incompatibly. */
+export declare const ALIAS_NAME_ARCHIVE_VERSION = 1;
+/** The persisted form of a Server's `LastChange` state. */
+export interface AliasNameArchive {
+    version: number;
+    /** Category NodeId (as a string) to VersionTime (UInt32 seconds since 2000-01-01Z). */
+    lastChange: Record<string, number>;
+}
+/**
+ * Read an archive, or return `null` when there is none.
+ *
+ * A missing file is normal — the first start. A corrupt or
+ * future-versioned file is **not** silently ignored: continuing with a zeroed
+ * `LastChange` is exactly the cache-clearing bug persistence exists to prevent,
+ * so the caller is told rather than left to discover it from a Client.
+ */
+export declare function readAliasNameArchive(path: string): Promise<AliasNameArchive | null>;
+/**
+ * Write an archive atomically.
+ *
+ * Temp file plus rename, so a crash mid-write leaves either the previous
+ * archive or the new one, never a truncated file that would fail to parse on
+ * the next start.
+ */
+export declare function writeAliasNameArchive(path: string, archive: AliasNameArchive): Promise<void>;

package/dist/alias_name_archive.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Persistence for `LastChange` (OPC 10000-17 clause 6.3.1).
+ *
+ * Clause 6.3.1 is blunt about why this exists: *"The LastChange shall be
+ * persisted. A Client that detects a LastChange that is older than what it has
+ * cached, shall clear all cached AliasNameCategories and related AliasNames."*
+ *
+ * So a restart that reset `LastChange` to zero would not merely lose
+ * information — it would order every connected Client to throw away a cache
+ * that is still perfectly valid, silently and on every restart. That is a
+ * Server-side bug whose only symptom is remote.
+ *
+ * The archive is plain JSON: a version and a map of category NodeId to
+ * VersionTime. There is nothing secret in it, so unlike the RoleSet archive it
+ * is not encrypted — it is a handful of integers describing when things last
+ * changed. Writes are atomic (temp file + rename) so a crash cannot leave a
+ * half-written archive, which would be worse than no archive at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALIAS_NAME_ARCHIVE_VERSION = void 0;
+exports.readAliasNameArchive = readAliasNameArchive;
+exports.writeAliasNameArchive = writeAliasNameArchive;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Bumped when the on-disk shape changes incompatibly. */
+exports.ALIAS_NAME_ARCHIVE_VERSION = 1;
+/**
+ * Read an archive, or return `null` when there is none.
+ *
+ * A missing file is normal — the first start. A corrupt or
+ * future-versioned file is **not** silently ignored: continuing with a zeroed
+ * `LastChange` is exactly the cache-clearing bug persistence exists to prevent,
+ * so the caller is told rather than left to discover it from a Client.
+ */
+async function readAliasNameArchive(path) {
+    let raw;
+    try {
+        raw = await node_fs_1.promises.readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`readAliasNameArchive: ${path} is not valid JSON. Delete it to start fresh, but note that a Client that has cached AliasNames will be told to clear its cache.`);
+    }
+    const archive = parsed;
+    if (archive.version !== exports.ALIAS_NAME_ARCHIVE_VERSION) {
+        throw new Error(`readAliasNameArchive: ${path} has version ${String(archive.version)}, expected ${exports.ALIAS_NAME_ARCHIVE_VERSION}`);
+    }
+    return { version: archive.version, lastChange: archive.lastChange ?? {} };
+}
+/**
+ * Write an archive atomically.
+ *
+ * Temp file plus rename, so a crash mid-write leaves either the previous
+ * archive or the new one, never a truncated file that would fail to parse on
+ * the next start.
+ */
+async function writeAliasNameArchive(path, archive) {
+    await node_fs_1.promises.mkdir((0, node_path_1.dirname)(path), { recursive: true });
+    const temporaryPath = `${path}.tmp`;
+    await node_fs_1.promises.writeFile(temporaryPath, JSON.stringify(archive, null, 2), "utf-8");
+    await node_fs_1.promises.rename(temporaryPath, path);
+}
+//# sourceMappingURL=alias_name_archive.js.map

package/dist/alias_name_archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias_name_archive.js","sourceRoot":"","sources":["../source/alias_name_archive.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAuBH,oDA2BC;AASD,sDAKC;AA9DD,qCAAyC;AACzC,yCAAoC;AAEpC,0DAA0D;AAC7C,QAAA,0BAA0B,GAAG,CAAC,CAAC;AAS5C;;;;;;;GAOG;AACI,KAAK,UAAU,oBAAoB,CAAC,IAAY;IACnD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACD,GAAG,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,CAAC;IACd,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CACX,yBAAyB,IAAI,kIAAkI,CAClK,CAAC;IACN,CAAC;IAED,MAAM,OAAO,GAAG,MAAmC,CAAC;IACpD,IAAI,OAAO,CAAC,OAAO,KAAK,kCAA0B,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACX,yBAAyB,IAAI,gBAAgB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,kCAA0B,EAAE,CACjH,CAAC;IACN,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAAyB;IAC/E,MAAM,kBAAE,CAAC,KAAK,CAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,GAAG,IAAI,MAAM,CAAC;IACpC,MAAM,kBAAE,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7E,MAAM,kBAAE,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC"}

package/dist/bind_alias_category.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Binding the Methods of a single `AliasNameCategoryType` instance, and creating
+ * new categories at runtime.
+ *
+ * This is the one binding path. `installAliasNamesOnAddressSpace` calls
+ * {@link bindAliasCategory} in its loop rather than doing the work itself, so a
+ * category created after installation cannot end up bound differently from one
+ * that was there at install time — or, worse, not bound at all. An unbound
+ * MANDATORY `FindAlias` is the exact defect this package exists to remove, and
+ * it should not be able to reappear at runtime.
+ */
+import type { IAddressSpace, ISessionContext, UAMethod, UAObject, UAObjectType, UAVariable } from "node-opcua-address-space-base";
+import type { IAliasStore } from "node-opcua-alias-name-common";
+import { type NodeId } from "node-opcua-nodeid";
+import type { RolePermissionTypeOptions } from "node-opcua-types";
+import { type AliasComparator } from "./bind_find_alias.js";
+import { type LastChangeTracker } from "./last_change.js";
+/** Everything a category needs in order to answer `FindAlias`. */
+export interface BindAliasCategoryOptions {
+    /** Where aliases come from. */
+    store: IAliasStore;
+    /** Result cap per call (clause 6.3.2 Table 4). */
+    maxResults: number;
+    /** Also bind `FindAliasVerbose`, adding the Method if the instance lacks it. */
+    verbose?: boolean;
+    /** Result ordering (clause 6.3.2, "best match first"). */
+    comparator?: AliasComparator;
+    /** Read gate; see {@link FindAliasBindingOptions.isReadAllowed}. */
+    isReadAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+    /**
+     * Write gate for the configuration Methods, mirroring `isReadAllowed`.
+     * Defaults to denying everyone.
+     */
+    isWriteAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+    /** Also add and bind `AddAliasesToCategory` / `DeleteAliasesFromCategory`. */
+    configurationMethods?: boolean;
+    /** Ensure the category carries a `LastChange` Property (clause 6.3.1). */
+    lastChangeProperty?: boolean;
+    /** Called after a configuration Method changed the category. */
+    onChanged?: (categoryNodeId: NodeId) => void | Promise<void>;
+}
+/**
+ * Bind `FindAlias` — and, when `verbose`, `FindAliasVerbose` — on one
+ * `AliasNameCategoryType` instance.
+ *
+ * Safe to call on a category that is already bound: `bindMethod` replaces the
+ * handler, and the optional Method is only added when it is missing.
+ *
+ * Use this for a category created after `installAliasNames` has run. The options
+ * that installation used are on {@link InstallAliasNamesResult.bindingOptions},
+ * so a caller does not have to reassemble them and risk binding a late category
+ * with a different store or a different result cap.
+ */
+export declare function bindAliasCategory(addressSpace: IAddressSpace, category: UAObject, options: BindAliasCategoryOptions): void;
+/**
+ * Ensure a category has a `LastChange` Property.
+ *
+ * `LastChange` is Optional on `AliasNameCategoryType` and the shipped nodeset
+ * instantiates it only on the `Aliases` root, which clause 9.2 makes mandatory.
+ * Adding it to every category is conformant — Optional means may, not must not —
+ * and it is what makes the clause 6.3.1 rollup observable: without it, a Client
+ * watching one branch has nothing to watch.
+ */
+export declare function ensureLastChangeProperty(addressSpace: IAddressSpace, category: UAObject): UAVariable | null;
+export interface AddAliasCategoryOptions extends Partial<BindAliasCategoryOptions> {
+    /**
+     * Namespace for the new category's BrowseName. Defaults to the Server's own.
+     */
+    namespaceIndex?: number;
+    /**
+     * NodeId for the new category. Defaults to a server-assigned one, which is
+     * correct for any category the specification does not name.
+     */
+    nodeId?: NodeId;
+    /**
+     * ObjectType to instantiate. Defaults to `AliasNameCategoryType`; a subtype
+     * is accepted, since discovery and binding both already handle subtypes.
+     */
+    categoryType?: UAObjectType | NodeId;
+    /**
+     * RolePermissions for the new category.
+     *
+     * Worth setting deliberately. Namespace 0 declares no `RolePermissions` on
+     * any Part 17 node, so a category created without them inherits the
+     * namespace default silently — which is a decision either way, just an
+     * invisible one.
+     */
+    rolePermissions?: RolePermissionTypeOptions[];
+}
+/**
+ * Create a vendor `AliasNameCategoryType` instance under `parent` **and bind it**.
+ *
+ * Creating one by hand means instantiating the type, wiring the `Organizes`
+ * reference and then remembering to bind — and a category whose `FindAlias` is
+ * unbound fails conformance silently. This does all three.
+ *
+ * When `installAliasNames` has already run on this address space, the binding
+ * options it used are reused unless overridden, so a category added at runtime
+ * behaves exactly like one that was present at install time. Pass a `store`
+ * explicitly if installation has not run yet.
+ */
+export declare function addAliasCategory(addressSpace: IAddressSpace, parent: UAObject | NodeId, browseName: string, options?: AddAliasCategoryOptions): UAObject;
+/**
+ * Remove a category, and decide what happens to what it Organizes.
+ *
+ * The specification does not say, so the rule is stated here rather than left to
+ * whatever `deleteNode` happens to do:
+ *
+ * - **`reparent`** (the default) moves the category's aliases and subcategories
+ *   to its parent before deleting it. Nothing disappears, so a Client that had
+ *   resolved an alias keeps resolving it — the alias Object keeps its NodeId,
+ *   and clause 6.2 makes a NodeId change mean "this is a different alias".
+ * - **`cascade`** deletes them with it. Correct when the category *is* the
+ *   thing being retired, such as a tenant being removed.
+ *
+ * Refuses to remove one of the three well-known categories, which clause 9
+ * requires a Server to have.
+ *
+ * @returns the aliases and subcategories that were re-parented, or deleted.
+ */
+export declare function removeAliasCategory(addressSpace: IAddressSpace, category: UAObject | NodeId, options?: {
+    orphans?: "reparent" | "cascade";
+}): {
+    moved: NodeId[];
+    deleted: NodeId[];
+};
+/**
+ * Find a Method on a category by its MethodDeclarationId, falling back to the
+ * BrowseName.
+ *
+ * The declaration id is the reliable key: a Server may publish the Method under
+ * a localised DisplayName, and the BrowseName is only unique within the
+ * namespace. The fallback covers instances built in code, which do not always
+ * carry a `methodDeclarationId`.
+ */
+export declare function findMethodByDeclaration(category: UAObject, declarationId: NodeId, browseName: string): UAMethod | null;
+/**
+ * Ensure an optional Method exists on a category, adding it when the nodeset
+ * only declared it on the type.
+ *
+ * The shipped `Opc.Ua.NodeSet2.xml` declares `FindAliasVerbose`,
+ * `AddAliasesToCategory` and `DeleteAliasesFromCategory` on
+ * `AliasNameCategoryType` but instantiates none of them on `Aliases`,
+ * `TagVariables` or `Topics`. Upstream nonetheless reserves fixed NodeIds for
+ * those instances, so where one exists it is used in preference to a
+ * server-assigned id; an aggregating Server then sees the NodeId it expects.
+ */
+export declare function ensureOptionalMethod(addressSpace: IAddressSpace, category: UAObject, name: "FindAliasVerbose" | "AddAliasesToCategory" | "DeleteAliasesFromCategory"): UAMethod | null;
+/**
+ * Marks an address space as already carrying AliasName bindings, so a second
+ * `installAliasNames` is a no-op rather than a double binding.
+ */
+export declare const INSTALLED: unique symbol;
+/** What installation recorded on the address space, if it has run. */
+export interface InstalledAliasNames {
+    store: IAliasStore;
+    categories: NodeId[];
+    bindingOptions: BindAliasCategoryOptions;
+    /** Keeps `LastChange` correct across the hierarchy (clause 6.3.1). */
+    lastChange?: LastChangeTracker;
+}
+/**
+ * What `installAliasNames` recorded on this address space, or undefined if it
+ * has not run.
+ *
+ * Exposed so a caller can rebind a late category with exactly the options
+ * installation used, without having to keep the install result around.
+ */
+export declare function getInstalledAliasNames(addressSpace: IAddressSpace): InstalledAliasNames | undefined;
+/** Record the installation on the address space. */
+export declare function setInstalledAliasNames(addressSpace: IAddressSpace, value: InstalledAliasNames): void;