@theotherwillembotha/node-red-plugincore 0.1.0 → 0.2.0

package/src/core/metrics/template/CounterMetricTemplate.html

@@ -4,7 +4,6 @@
 </script>
 
 <script type="text/javascript" template-section="onIncludeEditPrepare">
-
     let metricsEnabled = $("#node-{{#if config.isConfigNode}}config-{{/if}}input-metricsEnabled");
     let metricsEnabledSection = $("#section_metricsEnabled");
 

package/src/core/metrics/template/GaugeMetricTemplate.html

@@ -6,7 +6,7 @@
 <script type="text/javascript" template-section="onIncludeEditPrepare">
     let metricsEnabled = $("#node-{{#if config.isConfigNode}}config-{{/if}}input-metricsEnabled");
     let metricsEnabledSection = $("#section_metricsEnabled");
-
+    
     metricsEnabled.on('change', function() {
         if(metricsEnabled.prop("checked")){
             metricsEnabledSection.show();

package/src/core/metrics/template/MetricsTemplate.html

@@ -1,29 +1,138 @@
 <script type="text/javascript" template-section="onCompose">
     node
         .addDefault("metricsEnabled", { value:false, required:true})
-        .addDefault("metricsReference", {type:"MetricsConfigNode", required:false})
+        .addDefault("metricsReference", { required:false, value:'', type:"DelegatedConfigReferenceNode"})
 </script>
 
 <script type="text/javascript" template-section="onIncludeEditPrepare">
-    let node = this;   
-
     let metricsEnabled = $("#{{defaults.metricsEnabled}}");
-    let metricsEnabledSection = $("#section_metricsEnabled");
+    let metricsSection = $("#section_metricsconfig");
+    let metricsContainer = metricsEnabled.closest(".editorgroupborder");
+    let metricsEnabledSection = metricsContainer.find("#section_metricsEnabled");
+    metricsSection.hide();
+
+    let getMetricsProviderTypes = async function() {
+        let types = [];
+        await $.ajax({
+            url: "nodetypeservice/find?tag=MetricsProvider",
+            type: "GET",
+            contentType: "application/json; charset=utf-8",
+            success: (response) => { types = response; },
+            error: (jqXHR, textStatus, errorThrown) => { console.log(jqXHR, textStatus, errorThrown); },
+        });
+        return types;
+    };
+
+    let getMetricsProviders = async () => {
+        let providers = [];
+        let providerTypes = (await getMetricsProviderTypes()).map(t => t.id);
+        RED.nodes.eachConfig(cfg => {
+            if (providerTypes.includes(cfg.type)) {
+                providers.push({ id: cfg.id, name: cfg.label(), type: cfg.type });
+            }
+        });
+        return providers;
+    };
+
+    let updateMetricsSelectorList = async () => {
+        metricsSelector.empty();
+        (await getMetricsProviders()).forEach(provider => {
+            $('<option value="' + provider.id + '">' + provider.name + '</option>').appendTo(metricsSelector);
+        });
+        $('<option value="_ADD_">none</option>').appendTo(metricsSelector);
+    };
 
     metricsEnabled.on('change', function() {
-        if(metricsEnabled.prop("checked")){
+        if (metricsEnabled.prop("checked")) {
             metricsEnabledSection.show();
-            node._def.defaults.metricsReference.required = true;
+        } else {
+            metricsEnabledSection.hide();
+        }
+    });
+
+    let metricsSelector   = metricsContainer.find("#metrics-selector");
+    let metricsEditButton = metricsContainer.find("#metrics-edit-btn");
+    let metricsAddButton  = metricsContainer.find("#metrics-add-btn");
+
+    metricsEditButton.on('click', async function(event) {
+        event.stopPropagation();
+        if (metricsEditButton.hasClass("disabled")) return;
+        let selectedProvider = (await getMetricsProviders()).find(p => p.id === metricsSelector.val());
+        if (selectedProvider) {
+            RED.editor.editConfig("#metrics-selector", selectedProvider.type, selectedProvider.id);
         }
-        else{
-            metricsEnabledSection.hide()
-            node._def.defaults.metricsReference.required = false;
+    });
+
+
+    metricsAddButton.on('click', function(event) {
+        event.stopPropagation();
+        let $btn = $(event.currentTarget);
+        let btnOffset = $btn.offset();
+        let btnH = $btn.outerHeight();
+        let btnW = $btn.outerWidth();
+        $('.metricstype-dropdown').remove();
+
+        getMetricsProviderTypes().then(providerTypes => {
+            let $dropdown = $('<div class="metricstype-dropdown red-ui-editor"></div>').css({
+                position: 'absolute',
+                zIndex: 1000
+            });
+
+            providerTypes.forEach(providerType => {
+                $('<div class="dropdown-item"></div>')
+                    .text(providerType.name)
+                    .data('value', providerType.id)
+                    .css({ padding: '4px 8px', cursor: 'pointer' })
+                    .appendTo($dropdown);
+            });
+
+            $('body').append($dropdown);
+            $dropdown.css({
+                top:  btnOffset.top + btnH,
+                left: Math.max(0, btnOffset.left + btnW - $dropdown.outerWidth())
+            });
+
+            $(document).on('mousedown.metricsdropdown', function(e) {
+                if (!$(e.target).closest('.metricstype-dropdown').length) {
+                    $dropdown.remove();
+                    $(document).off('mousedown.metricsdropdown');
+                }
+            });
+
+            $dropdown.on('click', '.dropdown-item', function(e) {
+                e.stopPropagation();
+                const selectedValue = $(this).data('value');
+                $dropdown.remove();
+                RED.editor.editConfig("#metrics-selector", selectedValue, "_ADD_");
+            });
+        });
+    });
+
+    metricsSelector.on("focus", updateMetricsSelectorList);
+    metricsSelector.on('change', function() {
+        if ("_ADD_" === metricsSelector.val()) {
+            metricsEditButton.addClass("disabled");
+        } else {
+            metricsEditButton.removeClass("disabled");
         }
     });
+
+    // Show the metrics section only if at least one metrics provider type is registered.
+    // If nodered_prometheus (or any other provider) is not installed, the section stays hidden.
+    getMetricsProviderTypes().then(providerTypes => {
+        if (providerTypes.length === 0) return;
+        metricsSection.show();
+        updateMetricsSelectorList().then(() => {
+            metricsSelector.val(node.metricsReference);
+            metricsSelector.trigger('change');
+        });
+    });
 </script>
 
 <script type="text/javascript" template-section="onIncludeEditSave">
- 
+    node = this;
+    var selectedProvider = $("#metrics-selector").val();
+    node.metricsReference = (selectedProvider && selectedProvider !== "_ADD_") ? selectedProvider : '';
 </script>
 
 <script type="text/html" template-section="onIncludeEditForm">
@@ -39,8 +148,18 @@
 
             <div id="section_metricsEnabled">
                 <div class="form-row nomargin">
-                    <label class="towb_editorlabel" for="{{defaults.metricsReference}}">Metric Collector</label>
-                    <input id="{{defaults.metricsReference}}" placeholder="metrics" />
+                    <label class="towb_editorlabel" for="metrics-selector">Metric Provider</label>
+                    <div style="width: 70%; display: inline-flex;">
+                        <select id="metrics-selector" style="flex-grow: 1; min-width: 0;">
+                            <option value="_ADD_">none</option>
+                        </select>
+                        <a id="metrics-edit-btn" class="red-ui-button disabled" style="margin-left: 10px; flex-shrink: 0;">
+                            <i class="fa fa-pencil"></i>
+                        </a>
+                        <a id="metrics-add-btn" class="red-ui-button" style="margin-left: 10px; flex-shrink: 0;">
+                            <i class="fa fa-plus"></i>
+                        </a>
+                    </div>
                 </div>
             </div>
         </div>
@@ -50,5 +169,5 @@
 <script type="text/markdown" template-section="onIncludeDocumentation">
 ### Metrics
 : *enable metrics* (boolean) : if checked, then the node will produce metrics output to the specified metrics provider.
-: *metric collector* (metricconfig) : the collection point or grouping where this particular metric will be attached.
+: *metric provider* (metricsconfig) : the metrics backend that this node will report to.
 </script>

package/src/core/metrics/template/MetricsTemplate.ts

@@ -1,18 +1,17 @@
 import { SourceUtility } from "../../NodeGenerator";
 import { BaseNodeConfig, Template, TemplateDescriptor } from "../../NodeConstructor"
-import { MetricsConfigNode } from "../node/MetricsConfigNode";
 import { MetricsReference } from "../service/MetricsService";
 
 export interface MetricsTemplateConfig extends BaseNodeConfig, MetricsReference {
 }
 
 export class MetricsTemplate extends Template {
-   
+
     public static getTemplateDescriptor(): TemplateDescriptor {
         return new TemplateDescriptor(
             "metrics",
-            MetricsTemplate, 
+            MetricsTemplate,
             SourceUtility.getSourcePath("/build/", "/src/") + "MetricsTemplate.html",
-            [MetricsConfigNode]);
+            []);
     }
 }

package/src/core/other/node/DelegatedConfigReferenceNode.ts

@@ -1,6 +1,6 @@
 
 /**
- * DelegatedConfigReferenceNode — a framework-internal sentinel type.
+ * DelegatedConfigReferenceNode - a framework-internal sentinel type.
  *
  * PROBLEM
  * Node-RED's reference counter (the usage count shown on config nodes in the

package/src/core/other/service/SettingsService.ts

@@ -1,6 +1,11 @@
-import {BaseNode, BaseNodeConfig, BaseService, NodeManager, ServiceDescriptor} from "../../NodeConstructor"
+import {BaseNode, BaseNodeConfig, BaseService, NodeManager} from "../../NodeConstructor"
+import { ServiceDescription } from "../../tagging/ServiceDescriptionDecorator";
 import { Node, NodeAPI, NodeDef, NodeAPISettingsWithData} from "node-red";
 
+@ServiceDescription({
+    id: "@theotherwillembotha/settingsservice",
+    sourceFile: "@theotherwillembotha/node-red-plugincore"
+})
 export class SettingsService extends BaseService {
 
     static create(node:BaseNode<BaseNodeConfig>, config:SettingsConfig): Settings{
@@ -40,15 +45,6 @@ export class SettingsService extends BaseService {
         });
     }
 
-    static override getServiceDescriptor():ServiceDescriptor {
-        return new ServiceDescriptor(
-            "@theotherwillembotha/settingsservice",
-            "SettingsService",
-            "services-plugin",
-            "@theotherwillembotha/node-red-plugincore",
-            SettingsService
-        );
-    }
 }
 
 export class Settings{

package/src/core/other/template/BasicTemplate.html

@@ -70,7 +70,7 @@
         width: 30% !important;
     }
 
-    /* Node label colour helpers — use via .setLabelStyle() in onCompose */
+    /* Node label colour helpers - use via .setLabelStyle() in onCompose */
     .node_label_white { fill: white; }
     .node_label_black { fill: black; }
 </style>

package/src/core/state/node/InternalStateConfigNode.html

@@ -0,0 +1,77 @@
+<script type="text/javascript" template-section="onCompose">
+    node
+        .addDefault("name",             { value: "Internal State", required: true })
+        .addDefault("survivesRedeploy", { value: false, required: false })
+        .addDefault("survivesRestart",  { value: false, required: false })
+        .setPaletteLabel("Internal State")
+        .setLabel(function() { return this.name || "Internal State"; })
+</script>
+
+<script type="text/javascript" template-section="onIncludeEditPrepare">
+{
+    // Auto-populate the name from the consumer node's context when this is a fresh node.
+    let nameInput = $("#node-config-input-name");
+    let ctx = window.__stateTemplateContext || {};
+    if (ctx.defaultName && (!nameInput.val() || nameInput.val() === "Internal State")) {
+        nameInput.val(ctx.defaultName);
+    }
+    window.__stateTemplateContext = null;
+
+    // When "survives restart" is checked, "survives redeploy" must also be checked.
+    let survivesRestart  = $("#node-config-input-survivesRestart");
+    let survivesRedeploy = $("#node-config-input-survivesRedeploy");
+
+    survivesRestart.on("change", function() {
+        if (survivesRestart.prop("checked")) {
+            survivesRedeploy.prop("checked", true).prop("disabled", true);
+        } else {
+            survivesRedeploy.prop("disabled", false);
+        }
+    });
+
+    survivesRestart.trigger("change");
+}
+</script>
+
+<script type="text/javascript" template-section="onIncludeEditSave">
+</script>
+
+<script type="text/html" template-section="onIncludeEditForm">
+    <div class="form-row">
+        <span style="display:inline-block; padding: 4px 0; color:#888;">
+            <i class="fa fa-database" style="margin-right:6px;"></i>Internal State Provider
+        </span>
+    </div>
+
+    <!-- Name is stored but not shown - auto-set from the consumer node's name + suffix. -->
+    <input type="hidden" id="node-config-input-name" />
+
+    <div class="form-row editorsectionheading" style="margin-top:8px;">
+        <i class="w-16 fa fa-database"></i> <span>Persistence</span>
+    </div>
+    <div class="editorgroupborder">
+        <div class="form-row nomargin">
+            <input type="checkbox" id="node-config-input-survivesRedeploy" style="margin: 8px 0 10px 130px; width:20px;" />
+            <label style="width:auto;" for="node-config-input-survivesRedeploy">Survives redeploy</label>
+        </div>
+        <div class="form-row nomargin">
+            <input type="checkbox" id="node-config-input-survivesRestart" style="margin: 8px 0 10px 130px; width:20px;" />
+            <label style="width:auto;" for="node-config-input-survivesRestart">Survives restart <span style="color:#aaa; font-size:0.85em;">(also writes to disk)</span></label>
+        </div>
+    </div>
+</script>
+
+<script type="text/markdown" template-section="onIncludeDocumentation">
+Stores a named state value in memory, optionally persisted across redeployments or process restarts.
+
+### Properties
+
+: *survives redeploy* (boolean) : When checked, the current state value is preserved across Node-RED flow redeployments. When unchecked (default), state resets on each deploy.
+: *survives restart*  (boolean) : When checked, the current state is written to disk and restored after a process restart. Automatically implies "survives redeploy".
+
+### Details
+
+The initial (default) state value is provided by the node that owns this config - for example, a Circuit Breaker Config Node sets the state to its configured **Default State** if no value has been stored yet.
+
+When **Survives Restart** is enabled, state is persisted to `<userDir>/internalstate/<nodeId>.json` and automatically restored on the next startup.
+</script>

package/src/core/state/node/InternalStateConfigNode.ts

@@ -0,0 +1,102 @@
+import { Node } from "node-red";
+import { ConfigNodeConfig } from "../../NodeConstructor";
+import { NodeDescription } from "../../tagging/NodeDescriptionDecorator";
+import { SourceUtility } from "../../NodeGenerator";
+import { StateService, StateHandle } from "../service/StateService";
+import { StateConfigNode } from "./StateConfigNode";
+
+interface InternalStateConfigNodeConfig extends ConfigNodeConfig {
+    survivesRedeploy: boolean;
+    survivesRestart: boolean;
+}
+
+class InternalStateHandle implements StateHandle {
+    private _nodeId: string;
+    private _survivesRedeploy: boolean;
+    private _survivesRestart: boolean;
+    private _callback: ((s: string) => void) | null = null;
+
+    constructor(nodeId: string, survivesRedeploy: boolean, survivesRestart: boolean) {
+        this._nodeId = nodeId;
+        this._survivesRedeploy = survivesRedeploy;
+        this._survivesRestart = survivesRestart;
+        this._init();
+    }
+
+    private _init(): void {
+        // On process restart, memory is empty. If this node survives restarts, load from file.
+        if (this._survivesRestart && StateService.getMemory(this._nodeId) === null) {
+            const fileValue = StateService.readFile(this._nodeId);
+            if (fileValue !== null) {
+                StateService.setMemory(this._nodeId, fileValue);
+            }
+        }
+        // Default state seeding is the consumer node's responsibility - call set() after get() returns null.
+    }
+
+    private _read(): string | null {
+        return StateService.getMemory(this._nodeId);
+    }
+
+    private _write(value: string): void {
+        StateService.setMemory(this._nodeId, value);
+        if (this._survivesRestart) {
+            StateService.writeFile(this._nodeId, value);
+        }
+    }
+
+    public get(): Promise<string | null> {
+        return Promise.resolve(this._read());
+    }
+
+    public set(stateName: string): Promise<void> {
+        this._write(stateName);
+        StateService.notifySubscribers(this._nodeId, stateName);
+        return Promise.resolve();
+    }
+
+    public subscribe(callback: (stateName: string) => void): void {
+        this._callback = callback;
+        StateService.addSubscriber(this._nodeId, callback);
+    }
+
+    public unsubscribe(): void {
+        if (this._callback) {
+            StateService.removeSubscriber(this._nodeId, this._callback);
+            this._callback = null;
+        }
+    }
+}
+
+@NodeDescription({
+    id: "InternalStateConfigNode",
+    name: "Internal State Config Node",
+    group: "config",
+    sourceFile: SourceUtility.getSourcePath("/build/", "/src/") + "InternalStateConfigNode.html",
+    package: "@theotherwillembotha/node-red-plugincore",
+    dependencies: [StateService],
+    tags: ["StateProvider"]
+})
+export class InternalStateConfigNode extends StateConfigNode {
+    private _survivesRedeploy: boolean;
+    private _survivesRestart: boolean;
+
+    constructor(node: Node, config: InternalStateConfigNodeConfig) {
+        super(node, config);
+        this._survivesRedeploy = config.survivesRedeploy ?? false;
+        this._survivesRestart  = config.survivesRestart  ?? false;
+
+        StateService.registerConfig(config.id, {
+            survivesRedeploy: this._survivesRedeploy,
+            survivesRestart:  this._survivesRestart,
+        });
+    }
+
+    public createHandle(): StateHandle {
+        return new InternalStateHandle(
+            this.id(),
+            this._survivesRedeploy,
+            this._survivesRestart
+        );
+    }
+}

package/src/core/state/node/StateConfigNode.ts

@@ -0,0 +1,29 @@
+import { Node } from "node-red";
+import { ConfigNode, ConfigNodeConfig } from "../../NodeConstructor";
+import { StateHandle, StateService } from "../service/StateService";
+
+/**
+ * Abstract base for all state provider config nodes.
+ *
+ * Concrete implementations (e.g. InternalStateConfigNode, ZookeeperStateConfigNode) extend this
+ * class, decorate with @NodeDescription + tags: ["StateProvider"], and implement createHandle()
+ * to return their backend-specific StateHandle.
+ *
+ * This class is intentionally NOT decorated with @NodeDescription - it is never registered as a
+ * Node-RED node type directly. Only concrete subclasses are registered.
+ */
+export abstract class StateConfigNode extends ConfigNode<ConfigNodeConfig> {
+
+    constructor(node: Node, config: ConfigNodeConfig) {
+        super(node, config);
+        StateService.registerFactory(config.id, () => this.createHandle());
+    }
+
+    /**
+     * Creates a new StateHandle for a consumer node.
+     * Called once per consumer that references this config node.
+     * Each handle maintains its own subscriber slot, so multiple consumers
+     * can independently subscribe and unsubscribe without interfering.
+     */
+    public abstract createHandle(): StateHandle;
+}

package/src/core/state/service/StateService.ts

@@ -0,0 +1,180 @@
+import { BaseService, FlowDeployment } from "../../NodeConstructor";
+import { ServiceDescription } from "../../tagging/ServiceDescriptionDecorator";
+import { NodeAPI, NodeAPISettingsWithData } from "node-red";
+import * as fs from "fs";
+import * as path from "path";
+
+// ******************************************************* //
+//                   StateHandle                           //
+// ******************************************************* //
+
+export interface StateHandle {
+    get(): Promise<string | null>;
+    set(stateName: string): Promise<void>;
+    subscribe(callback: (stateName: string) => void): void;
+    unsubscribe(): void;
+}
+
+export class DoNothingStateHandle implements StateHandle {
+    public get(): Promise<string | null> { return Promise.resolve(null); }
+    public set(_stateName: string): Promise<void> { return Promise.resolve(); }
+    public subscribe(_callback: (stateName: string) => void): void {}
+    public unsubscribe(): void {}
+}
+
+// (StateReference removed - stateEnabled is no longer optional; consumers pass the ID directly)
+
+// ******************************************************* //
+//                   Global Store Keys                     //
+// ******************************************************* //
+
+const _GLOBAL_STATE_MEMORY_KEY    = '__plugincore_internalstate_memory__';
+const _GLOBAL_STATE_SUBS_KEY      = '__plugincore_internalstate_subscribers__';
+const _GLOBAL_STATE_FACTORIES_KEY = '__plugincore_state_factories__';
+const _GLOBAL_STATE_CONFIG_KEY    = '__plugincore_state_config__';
+const _GLOBAL_STATE_USERDIR_KEY   = '__plugincore_state_userDir__';
+
+function getMemoryStore(): Map<string, string> {
+    if (!(global as any)[_GLOBAL_STATE_MEMORY_KEY]) (global as any)[_GLOBAL_STATE_MEMORY_KEY] = new Map();
+    return (global as any)[_GLOBAL_STATE_MEMORY_KEY];
+}
+
+function getSubscriberStore(): Map<string, Set<(s: string) => void>> {
+    if (!(global as any)[_GLOBAL_STATE_SUBS_KEY]) (global as any)[_GLOBAL_STATE_SUBS_KEY] = new Map();
+    return (global as any)[_GLOBAL_STATE_SUBS_KEY];
+}
+
+function getFactoryStore(): Map<string, () => StateHandle> {
+    if (!(global as any)[_GLOBAL_STATE_FACTORIES_KEY]) (global as any)[_GLOBAL_STATE_FACTORIES_KEY] = new Map();
+    return (global as any)[_GLOBAL_STATE_FACTORIES_KEY];
+}
+
+function getConfigStore(): Map<string, { survivesRedeploy: boolean; survivesRestart: boolean }> {
+    if (!(global as any)[_GLOBAL_STATE_CONFIG_KEY]) (global as any)[_GLOBAL_STATE_CONFIG_KEY] = new Map();
+    return (global as any)[_GLOBAL_STATE_CONFIG_KEY];
+}
+
+function getUserDir(): string | undefined {
+    return (global as any)[_GLOBAL_STATE_USERDIR_KEY];
+}
+
+function stateFilePath(nodeId: string): string | null {
+    const userDir = getUserDir();
+    if (!userDir) return null;
+    return path.join(userDir, 'internalstate', nodeId + '.json');
+}
+
+// ******************************************************* //
+//                   StateService                          //
+// ******************************************************* //
+
+@ServiceDescription({
+    id: "@theotherwillembotha/stateservice",
+    name: "StateService",
+    type: "integration-plugin",
+    sourceFile: "@theotherwillembotha/node-red-plugincore",
+})
+export class StateService extends BaseService {
+
+    constructor() {
+        super("StateService");
+    }
+
+    public init(red: NodeAPI<NodeAPISettingsWithData>): void {
+        (global as any)[_GLOBAL_STATE_USERDIR_KEY] = (red.settings as any).userDir;
+    }
+
+    public deinit(_red: NodeAPI<NodeAPISettingsWithData>): void {}
+
+    public async onDeploy(deployment: FlowDeployment): Promise<void> {
+        const flowIds = new Set(deployment.flows.map(e => e.id));
+        const factories = getFactoryStore();
+        const configs = getConfigStore();
+        const memory = getMemoryStore();
+
+        // Remove factories for config nodes no longer in the flow.
+        factories.forEach((_, nodeId) => {
+            if (!flowIds.has(nodeId)) factories.delete(nodeId);
+        });
+
+        // Clear memory for state config nodes that are gone or do not survive redeploy.
+        configs.forEach((cfg, nodeId) => {
+            if (!flowIds.has(nodeId)) {
+                memory.delete(nodeId);
+                configs.delete(nodeId);
+            } else if (!cfg.survivesRedeploy && !cfg.survivesRestart) {
+                memory.delete(nodeId);
+            }
+        });
+
+        return Promise.resolve();
+    }
+
+    // ---- Factory registration (called by StateConfigNode subclasses) ----
+
+    public static registerFactory(nodeId: string, factory: () => StateHandle): void {
+        getFactoryStore().set(nodeId, factory);
+    }
+
+    public static registerConfig(nodeId: string, config: { survivesRedeploy: boolean; survivesRestart: boolean }): void {
+        getConfigStore().set(nodeId, config);
+    }
+
+    // ---- Handle creation (called by consumer nodes) ----
+
+    public static createHandle(stateReference: string): StateHandle {
+        if (!stateReference) return new DoNothingStateHandle();
+        const factory = getFactoryStore().get(stateReference);
+        return factory ? factory() : new DoNothingStateHandle();
+    }
+
+    // ---- Memory store (used by InternalStateHandle) ----
+
+    public static getMemory(nodeId: string): string | null {
+        return getMemoryStore().get(nodeId) ?? null;
+    }
+
+    public static setMemory(nodeId: string, value: string): void {
+        getMemoryStore().set(nodeId, value);
+    }
+
+    // ---- File store (used by InternalStateHandle) ----
+
+    public static readFile(nodeId: string): string | null {
+        const filePath = stateFilePath(nodeId);
+        if (!filePath) return null;
+        try {
+            if (!fs.existsSync(filePath)) return null;
+            const content = fs.readFileSync(filePath, 'utf8');
+            return JSON.parse(content).value ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    public static writeFile(nodeId: string, value: string): void {
+        const filePath = stateFilePath(nodeId);
+        if (!filePath) return;
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify({ value }), 'utf8');
+    }
+
+    // ---- Subscriber management (used by InternalStateHandle) ----
+
+    public static addSubscriber(nodeId: string, callback: (s: string) => void): void {
+        const store = getSubscriberStore();
+        if (!store.has(nodeId)) store.set(nodeId, new Set());
+        store.get(nodeId)!.add(callback);
+    }
+
+    public static removeSubscriber(nodeId: string, callback: (s: string) => void): void {
+        getSubscriberStore().get(nodeId)?.delete(callback);
+    }
+
+    public static notifySubscribers(nodeId: string, value: string): void {
+        getSubscriberStore().get(nodeId)?.forEach(cb => {
+            try { cb(value); } catch {}
+        });
+    }
+}