@mxtommy/kip 4.7.0-beta.2 → 4.7.0-beta.4

package/plugin/kip-plugin/src/index.js

@@ -0,0 +1,1194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_api_1 = require("@signalk/server-api");
+const openapi = __importStar(require("./openApi.json"));
+const history_series_service_1 = require("./history-series.service");
+const sqlite_history_storage_service_1 = require("./sqlite-history-storage.service");
+async function defaultGetSqliteModule() {
+    try {
+        return await Promise.resolve().then(() => __importStar(require('node:sqlite')));
+    }
+    catch {
+        return null;
+    }
+}
+const start = (server) => {
+    const mutableOpenApi = JSON.parse(JSON.stringify(openapi.default ?? openapi));
+    const API_PATHS = {
+        DISPLAYS: `/displays`,
+        INSTANCE: `/displays/:displayId`,
+        SCREEN_INDEX: `/displays/:displayId/screenIndex`,
+        ACTIVATE_SCREEN: `/displays/:displayId/activeScreen`,
+        SERIES: '/series',
+        SERIES_INSTANCE: '/series/:seriesId',
+        SERIES_RECONCILE: '/series/reconcile',
+    };
+    const PUT_CONTEXT = 'vessels.self';
+    const COMMAND_PATHS = {
+        SET_DISPLAY: 'kip.remote.setDisplay',
+        SET_SCREEN_INDEX: 'kip.remote.setScreenIndex',
+        REQUEST_ACTIVE_SCREEN: 'kip.remote.requestActiveScreen'
+    };
+    const CONFIG_SCHEMA = {
+        type: 'object',
+        title: 'Remote Control and Data Series',
+        description: 'NOTE: All plugin settings are also managed from within KIP\'s Display Options panel. Changes made here will be overridden when KIP applies settings from the Display Options.',
+        properties: {
+            nodeSqliteAvailable: {
+                type: 'boolean',
+                title: 'node:sqlite Available',
+                description: 'Indicates if node:sqlite is available in the current runtime (requires Node.js version 22.5.0 or newer). This is set automatically and is read-only.\n\nBefore upgrading Node.js, always verify compatibility with your Signal K server version at https://demo.signalk.org/documentation.',
+                readOnly: true
+            },
+            historySeriesServiceEnabled: {
+                type: 'boolean',
+                title: 'Enable Automatic Historical Time-Series Capture and Management',
+                description: 'Historical Time-Series are data captures that supply the widget historical data and seed the Data Chart and Wind Trends widgets. If disabled, data capture must be configured in your chosen history provider plugin.',
+                default: true
+            },
+            registerAsHistoryApiProvider: {
+                type: 'boolean',
+                title: 'Enable Query Provider',
+                description: 'The built-in History-API query provider is a feature that enables the plugin to respond to History-API requests. If you want to use another History-API provider, disable this option and configure your chosen History-API compatible provider accordingly and KIP will query that provider.',
+                default: true
+            }
+        }
+    };
+    const historySeries = new history_series_service_1.HistorySeriesService(() => Date.now(), typeof server.selfId === 'string' && server.selfId.trim().length > 0 ? `vessels.${server.selfId.trim()}` : null);
+    const storageService = new sqlite_history_storage_service_1.SqliteHistoryStorageService(server.app.getDataDirPath());
+    let retentionSweepTimer = null;
+    let storageFlushTimer = null;
+    let sqliteInitializationPromise = null;
+    const SQLITE_INIT_WAIT_TIMEOUT_MS = 5000;
+    const MIN_NODE_SQLITE_VERSION = '22.5.0';
+    let streamUnsubscribes = [];
+    let historyApiProviderRegistered = false;
+    let runtimeSqliteUnavailableMessage = null;
+    function logRuntimeDependencyVersions() {
+        const nodeIdentity = `node@${process.version}`;
+        const sqliteAvailability = modeConfig && modeConfig.nodeSqliteAvailable ? 'available' : 'unavailable';
+        server.debug(`[KIP][RUNTIME] ${nodeIdentity} node:sqlite=${sqliteAvailability}`);
+    }
+    async function detectSqliteRuntime() {
+        const exportedStart = start;
+        const resolveSqliteModule = typeof exportedStart.getSqliteModule === 'function'
+            ? exportedStart.getSqliteModule
+            : defaultGetSqliteModule;
+        const sqliteModule = await resolveSqliteModule();
+        if (!sqliteModule) {
+            runtimeSqliteUnavailableMessage = `node:sqlite requires Node ${MIN_NODE_SQLITE_VERSION}+`;
+            return false;
+        }
+        if (!sqliteModule.DatabaseSync && !sqliteModule.Database) {
+            runtimeSqliteUnavailableMessage = 'node:sqlite module missing required exports';
+            return false;
+        }
+        runtimeSqliteUnavailableMessage = null;
+        return true;
+    }
+    function getSqliteUnavailableMessage() {
+        if (!(modeConfig && modeConfig.nodeSqliteAvailable)) {
+            return `node:sqlite is not supported in the installed Node.js runtime. Node ${MIN_NODE_SQLITE_VERSION}+ is required.`;
+        }
+        const details = storageService.getLastInitError();
+        return details
+            ? `node:sqlite storage unavailable: ${details}`
+            : 'node:sqlite storage unavailable';
+    }
+    function isSqliteUnavailable() {
+        return !(modeConfig && modeConfig.nodeSqliteAvailable) || Boolean(storageService.getLastInitError());
+    }
+    function resolveHistoryModeConfig(settings) {
+        const root = (settings && typeof settings === 'object' ? settings : {});
+        const historySeriesServiceEnabledSetting = typeof root.historySeriesServiceEnabled === 'boolean'
+            ? root.historySeriesServiceEnabled
+            : undefined;
+        const registerAsHistoryApiProviderSetting = typeof root.registerAsHistoryApiProvider === 'boolean'
+            ? root.registerAsHistoryApiProvider
+            : undefined;
+        const nodeSqliteAvailable = typeof root.nodeSqliteAvailable === 'boolean'
+            ? root.nodeSqliteAvailable
+            : undefined;
+        return {
+            historySeriesServiceEnabled: historySeriesServiceEnabledSetting !== false,
+            registerAsHistoryApiProvider: registerAsHistoryApiProviderSetting !== false,
+            nodeSqliteAvailable: nodeSqliteAvailable !== false
+        };
+    }
+    function slugify(value) {
+        return value
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+    }
+    function resolveBmsBatteryIdsFromSelfPath() {
+        const batteriesPath = server.getSelfPath('electrical.batteries');
+        const readCandidate = (node) => {
+            if (!node || typeof node !== 'object' || Array.isArray(node)) {
+                return null;
+            }
+            const root = node;
+            if (Object.prototype.hasOwnProperty.call(root, 'value')) {
+                const value = root.value;
+                if (value && typeof value === 'object' && !Array.isArray(value)) {
+                    return value;
+                }
+                return null;
+            }
+            return root;
+        };
+        const candidates = readCandidate(batteriesPath);
+        if (!candidates) {
+            return [];
+        }
+        return Object.keys(candidates)
+            .filter(id => /^[a-z0-9_-]+$/i.test(id))
+            .sort((left, right) => left.localeCompare(right));
+    }
+    function getExistingConcreteBmsSeries(templateSeries, existingSeries) {
+        return existingSeries
+            .filter(series => series.ownerWidgetUuid === templateSeries.ownerWidgetUuid)
+            .filter(history_series_service_1.isKipConcreteSeriesDefinition)
+            .filter(series => series.seriesId !== templateSeries.seriesId)
+            .map(series => ({ ...series }));
+    }
+    function mergeSeriesDefinitions(series) {
+        const mergedById = new Map();
+        series.forEach(item => {
+            mergedById.set(item.seriesId, item);
+        });
+        return Array.from(mergedById.values());
+    }
+    function expandTemplateSeriesDefinitions(payload, existingSeries = []) {
+        const bmsMetrics = ['capacity.stateOfCharge', 'current'];
+        const expandedById = new Map();
+        const discoveredBatteryIds = resolveBmsBatteryIdsFromSelfPath();
+        payload.forEach(series => {
+            if (!(0, history_series_service_1.isKipTemplateSeriesDefinition)(series)) {
+                expandedById.set(series.seriesId, series);
+                return;
+            }
+            if (discoveredBatteryIds.length === 0) {
+                getExistingConcreteBmsSeries(series, existingSeries).forEach(existing => {
+                    expandedById.set(existing.seriesId, existing);
+                });
+                return;
+            }
+            const allowedBatteryIds = Array.isArray(series.allowedBatteryIds)
+                ? series.allowedBatteryIds
+                    .filter((id) => typeof id === 'string')
+                    .map(id => id.trim())
+                    .filter(id => id.length > 0)
+                : [];
+            const allowedSet = allowedBatteryIds.length > 0 ? new Set(allowedBatteryIds) : null;
+            const batteryIds = discoveredBatteryIds.filter(id => !allowedSet || allowedSet.has(id));
+            if (batteryIds.length === 0) {
+                return;
+            }
+            const source = series.source ?? 'default';
+            const sourceKey = slugify(source || 'default') || 'default';
+            batteryIds.forEach(batteryId => {
+                bmsMetrics.forEach(metric => {
+                    const path = `self.electrical.batteries.${batteryId}.${metric}`;
+                    const seriesId = `${series.ownerWidgetUuid}:bms:${batteryId}:${metric}:${sourceKey}`;
+                    expandedById.set(seriesId, {
+                        ...series,
+                        seriesId,
+                        datasetUuid: `${series.ownerWidgetUuid}:bms:${batteryId}:${metric}:${sourceKey}`,
+                        path,
+                        retentionDurationMs: Number.isFinite(series.retentionDurationMs) ? series.retentionDurationMs : 24 * 60 * 60 * 1000,
+                        expansionMode: null
+                    });
+                });
+            });
+        });
+        return Array.from(expandedById.values());
+    }
+    function getDisplaySelfPath(displayId, suffix) {
+        const tail = suffix ? `.${suffix}` : '';
+        const want = `displays.${displayId}${tail}`;
+        const full = server.getSelfPath(want);
+        server.debug(`[KIP][SELF_PATH] displayId=${displayId} suffix=${String(suffix ?? '')} requested=${want} resolved=${JSON.stringify(full)}`);
+        return typeof full === 'object' && full !== null ? full : undefined;
+    }
+    function getAvailableDisplays() {
+        const fullPath = server.getSelfPath('displays');
+        server.debug(`[KIP][DISPLAYS] resolved=${JSON.stringify(fullPath)}`);
+        return typeof fullPath === 'object' && fullPath !== null ? fullPath : undefined;
+    }
+    function sendOk(res, body) {
+        if (body === undefined)
+            return res.status(204).end();
+        return res.status(200).json(body);
+    }
+    function sendFail(res, statusCode, message) {
+        return res.status(statusCode).json({ state: 'FAILED', statusCode, message });
+    }
+    function getHistorySeriesServiceDisabledMessage() {
+        return 'KIP history-series service is disabled by plugin configuration';
+    }
+    async function waitForSqliteInitialization(timeoutMs = SQLITE_INIT_WAIT_TIMEOUT_MS) {
+        if (!sqliteInitializationPromise) {
+            return storageService.isSqliteReady();
+        }
+        try {
+            const ready = await Promise.race([
+                sqliteInitializationPromise,
+                new Promise(resolvePromise => {
+                    setTimeout(() => resolvePromise(false), timeoutMs);
+                })
+            ]);
+            if (!ready && !storageService.isSqliteReady()) {
+                server.error(`[SERIES STORAGE] node:sqlite initialization wait timed out after ${timeoutMs}ms`);
+            }
+            return ready;
+        }
+        catch {
+            return false;
+        }
+    }
+    function getRouteError(error, fallbackMessage) {
+        const message = String(error?.message || fallbackMessage);
+        const normalized = message.toLowerCase();
+        if (normalized.includes('invalid ')
+            || normalized.includes('missing ')
+            || normalized.includes('body must')
+            || normalized.includes('required')
+            || normalized.includes('expected an iso')) {
+            return { statusCode: 400, message };
+        }
+        if (normalized.includes('sqlite')
+            || normalized.includes('storage unavailable')
+            || normalized.includes('not initialized')
+            || isSqliteUnavailable()) {
+            return { statusCode: 503, message };
+        }
+        return { statusCode: 500, message };
+    }
+    function findSeriesById(seriesId) {
+        const current = historySeries.findSeriesById(seriesId);
+        return current ? JSON.parse(JSON.stringify(current)) : null;
+    }
+    function isHistorySeriesServiceEnabled() {
+        return !!(modeConfig && modeConfig.historySeriesServiceEnabled && modeConfig.nodeSqliteAvailable);
+    }
+    function isHistoryApiProviderEnabled() {
+        return !!(modeConfig && modeConfig.registerAsHistoryApiProvider && modeConfig.nodeSqliteAvailable);
+    }
+    function logOperationalMode(stage) {
+        server.debug(`[HISTORY MODE] stage=${stage} historySeriesServiceEnabled=${isHistorySeriesServiceEnabled()} historyApiProviderEnabled=${isHistoryApiProviderEnabled()} historyApiProviderRegistered=${historyApiProviderRegistered}`);
+    }
+    async function ensureSqliteReadyForRequest(res) {
+        await waitForSqliteInitialization();
+        if (storageService.isSqliteReady()) {
+            return true;
+        }
+        sendFail(res, 503, getSqliteUnavailableMessage());
+        return false;
+    }
+    function ensureHistorySeriesServiceEnabledForRequest(res) {
+        if (!(modeConfig && modeConfig.nodeSqliteAvailable)) {
+            sendFail(res, 503, getSqliteUnavailableMessage());
+            return false;
+        }
+        if (isHistorySeriesServiceEnabled()) {
+            return true;
+        }
+        sendFail(res, 503, getHistorySeriesServiceDisabledMessage());
+        return false;
+    }
+    function logAuthTrace(req, stage) {
+        const hasAuthorizationHeader = typeof req.headers.authorization === 'string' && req.headers.authorization.length > 0;
+        const hasCookieHeader = typeof req.headers.cookie === 'string' && req.headers.cookie.length > 0;
+        const origin = req.headers.origin ?? null;
+        const userAgent = req.headers['user-agent'] ?? null;
+        const contentType = req.headers['content-type'] ?? null;
+        server.debug(`[AUTH TRACE] stage=${stage} method=${req.method} path=${req.path} ip=${req.ip} origin=${String(origin)} authHeader=${hasAuthorizationHeader} cookieHeader=${hasCookieHeader} contentType=${String(contentType)} userAgent=${String(userAgent)}`);
+    }
+    function completed(statusCode, message) {
+        return { state: 'COMPLETED', statusCode, message };
+    }
+    function isValidDisplayId(displayId) {
+        return typeof displayId === 'string' && /^[A-Za-z0-9-]+$/.test(displayId);
+    }
+    function applyDisplayWrite(displayId, suffix, value) {
+        const path = suffix ? `displays.${displayId}.${suffix}` : `displays.${displayId}`;
+        server.debug(`[KIP][WRITE] applyDisplayWrite path=${path} value=${JSON.stringify(value)}`);
+        try {
+            server.handleMessage(plugin.id, {
+                updates: [
+                    {
+                        values: [
+                            {
+                                path: path,
+                                value: value ?? null
+                            }
+                        ]
+                    }
+                ]
+            }, server_api_1.SKVersion.v1);
+            server.debug(`[KIP][WRITE] handleMessage success path=${path}`);
+            return completed(200);
+        }
+        catch (error) {
+            const message = error?.message ?? 'Unable to write display path';
+            server.error(`[WRITE TRACE] handleMessage failure path=${path} message=${message}`);
+            return completed(400, message);
+        }
+    }
+    function handleSetDisplay(value) {
+        server.debug(`[KIP][COMMAND] handleSetDisplay payload=${JSON.stringify(value)}`);
+        const command = value;
+        if (!command || typeof command !== 'object') {
+            return completed(400, 'Command payload is required');
+        }
+        if (!isValidDisplayId(command.displayId)) {
+            return completed(400, 'Invalid displayId format');
+        }
+        const displayValue = command.display ?? null;
+        if (displayValue !== null && typeof displayValue !== 'object') {
+            return completed(400, 'display must be an object or null');
+        }
+        return applyDisplayWrite(command.displayId, null, displayValue);
+    }
+    function handleScreenWrite(value, suffix) {
+        server.debug(`[KIP][COMMAND] handleScreenWrite suffix=${suffix} payload=${JSON.stringify(value)}`);
+        const command = value;
+        if (!command || typeof command !== 'object') {
+            return completed(400, 'Command payload is required');
+        }
+        if (!isValidDisplayId(command.displayId)) {
+            return completed(400, 'Invalid displayId format');
+        }
+        const screenIdxValue = command.screenIdx ?? null;
+        if (screenIdxValue !== null && typeof screenIdxValue !== 'number') {
+            return completed(400, 'screenIdx must be a number or null');
+        }
+        return applyDisplayWrite(command.displayId, suffix, screenIdxValue);
+    }
+    function sendActionAsRest(res, result) {
+        server.debug(`[KIP][REST] sendActionAsRest statusCode=${result.statusCode} message=${result.message ?? ''}`);
+        if (result.statusCode === 200) {
+            return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
+        }
+        return sendFail(res, result.statusCode || 400, result.message || 'Command failed');
+    }
+    function stopSeriesCapture() {
+        streamUnsubscribes.forEach(unsub => {
+            try {
+                unsub();
+            }
+            catch {
+                // ignore unsubscribe failures
+            }
+        });
+        streamUnsubscribes = [];
+    }
+    function toIsoString(value) {
+        if (typeof value === 'string' && value.trim()) {
+            return value;
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (value && typeof value === 'object' && typeof value.toString === 'function') {
+            const serialized = value.toString();
+            return serialized && serialized !== '[object Object]' ? serialized : undefined;
+        }
+        return undefined;
+    }
+    function toDurationString(value) {
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === 'string' && value.trim()) {
+            return value;
+        }
+        if (value && typeof value === 'object' && typeof value.toString === 'function') {
+            const serialized = value.toString();
+            return serialized && serialized !== '[object Object]' ? serialized : undefined;
+        }
+        return undefined;
+    }
+    function normalizeHistoryMethod(method) {
+        const raw = String(method ?? 'avg').trim().toLowerCase();
+        if (raw === 'average') {
+            return 'avg';
+        }
+        if (raw === 'min' || raw === 'max' || raw === 'sma' || raw === 'ema' || raw === 'avg') {
+            return raw;
+        }
+        return 'avg';
+    }
+    function normalizeHistoryPath(path) {
+        const trimmed = typeof path === 'string' ? path.trim() : '';
+        if (!trimmed) {
+            return '';
+        }
+        if (trimmed.startsWith('vessels.self.')) {
+            return trimmed.slice('vessels.self.'.length);
+        }
+        if (trimmed.startsWith('self.')) {
+            return trimmed.slice('self.'.length);
+        }
+        return trimmed;
+    }
+    function buildPathsFromPathSpecs(pathSpecs) {
+        if (!Array.isArray(pathSpecs)) {
+            return '';
+        }
+        const specs = pathSpecs;
+        const encoded = specs
+            .map(spec => {
+            const path = normalizeHistoryPath(spec.path);
+            if (!path) {
+                return '';
+            }
+            const method = normalizeHistoryMethod(spec.aggregate);
+            const params = Array.isArray(spec.parameter)
+                ? spec.parameter.map(item => String(item).trim()).filter(Boolean)
+                : [];
+            return [path, method, ...params].join(':');
+        })
+            .filter(Boolean);
+        return encoded.join(',');
+    }
+    function buildHistoryQueryFromValuesRequest(query) {
+        const from = toIsoString(query?.from);
+        const to = toIsoString(query?.to);
+        const duration = toDurationString(query?.duration);
+        const paths = buildPathsFromPathSpecs(query?.pathSpecs);
+        return {
+            paths,
+            context: typeof query?.context === 'string' ? query.context : undefined,
+            from,
+            to,
+            duration,
+            resolution: typeof query?.resolution === 'number' || typeof query?.resolution === 'string' ? query.resolution : undefined
+        };
+    }
+    function buildHistoryQueryFromRangeRequest(query) {
+        return {
+            from: toIsoString(query?.from),
+            to: toIsoString(query?.to),
+            duration: toDurationString(query?.duration)
+        };
+    }
+    async function resolveHistoryPaths(query) {
+        await waitForSqliteInitialization();
+        if (!storageService.isSqliteReady()) {
+            throw new Error(getSqliteUnavailableMessage());
+        }
+        try {
+            await storageService.flush();
+        }
+        catch (flushError) {
+            server.error(`[SERIES STORAGE] pre-paths flush failed: ${String(flushError.message || flushError)}`);
+        }
+        return storageService.getStoredPaths({
+            ...(query ?? {})
+        });
+    }
+    async function resolveHistoryContexts(query) {
+        await waitForSqliteInitialization();
+        if (!storageService.isSqliteReady()) {
+            throw new Error(getSqliteUnavailableMessage());
+        }
+        try {
+            await storageService.flush();
+        }
+        catch (flushError) {
+            server.error(`[SERIES STORAGE] pre-contexts flush failed: ${String(flushError.message || flushError)}`);
+        }
+        return storageService.getStoredContexts({
+            ...(query ?? {})
+        });
+    }
+    async function resolveHistoryValues(query) {
+        await waitForSqliteInitialization();
+        if (!storageService.isSqliteReady()) {
+            throw new Error(getSqliteUnavailableMessage());
+        }
+        try {
+            await storageService.flush();
+        }
+        catch (flushError) {
+            server.error(`[SERIES STORAGE] pre-query flush failed: ${String(flushError.message || flushError)}`);
+        }
+        const values = await storageService.getValues({
+            ...query
+        });
+        if (!values) {
+            throw new Error('node:sqlite storage did not return history values.');
+        }
+        return values;
+    }
+    function registerHistoryProvider() {
+        historyApiProviderRegistered = false;
+        if (!isHistoryApiProviderEnabled()) {
+            server.debug('[KIP][HISTORY_PROVIDER] registration skipped reason=config-disabled');
+            return;
+        }
+        const serverWithHistoryApi = server;
+        const registerHistoryApiProvider = typeof serverWithHistoryApi.registerHistoryApiProvider === 'function'
+            ? serverWithHistoryApi.registerHistoryApiProvider.bind(serverWithHistoryApi)
+            : (typeof serverWithHistoryApi.history?.registerHistoryApiProvider === 'function'
+                ? serverWithHistoryApi.history.registerHistoryApiProvider.bind(serverWithHistoryApi.history)
+                : null);
+        // guard when running in SK variants that do not support History API registration
+        if (!registerHistoryApiProvider) {
+            server.debug('[KIP][HISTORY_PROVIDER] registration skipped reason=api-unavailable');
+            return;
+        }
+        const apiProvider = {
+            getValues: async (query) => {
+                const resolved = await resolveHistoryValues(buildHistoryQueryFromValuesRequest(query));
+                return {
+                    ...resolved,
+                    values: resolved.values.map(valueSpec => ({
+                        path: valueSpec.path,
+                        method: valueSpec.method === 'avg' ? 'average' : valueSpec.method
+                    }))
+                };
+            },
+            getPaths: (query) => resolveHistoryPaths(buildHistoryQueryFromRangeRequest(query)),
+            getContexts: (query) => resolveHistoryContexts(buildHistoryQueryFromRangeRequest(query))
+        };
+        registerHistoryApiProvider(apiProvider);
+        historyApiProviderRegistered = true;
+        server.debug('[KIP][HISTORY_PROVIDER] registration success provider=kip');
+    }
+    function rebuildSeriesCaptureSubscriptions() {
+        stopSeriesCapture();
+        if (!isHistorySeriesServiceEnabled()) {
+            return;
+        }
+        const streamBundle = server.streambundle;
+        if (!streamBundle || typeof streamBundle.getBus !== 'function') {
+            // server.debug('[SERIES CAPTURE] streambundle.getBus not available; capture disabled');
+            return;
+        }
+        const subscriptionCandidates = new Map();
+        const addCandidate = (path, allSelfContext) => {
+            const normalized = typeof path === 'string' ? path.trim() : '';
+            if (!normalized) {
+                return;
+            }
+            const existing = subscriptionCandidates.get(normalized);
+            if (!existing) {
+                subscriptionCandidates.set(normalized, { allSelfContext });
+                return;
+            }
+            // If any series for this path requires non-self context, force generic bus subscription.
+            existing.allSelfContext = existing.allSelfContext && allSelfContext;
+        };
+        historySeries.listSeries().filter(history_series_service_1.isKipSeriesEnabled).forEach(series => {
+            const allSelfContext = (series.context ?? 'vessels.self') === 'vessels.self';
+            addCandidate(series.path, allSelfContext);
+            // Workaround: subscribe to immediate parent path so object deltas (e.g. navigation.attitude)
+            // are captured and flattened into leaf numeric paths (e.g. navigation.attitude.pitch).
+            // Remove this fallback when KIP adds first-class object-path capture support.
+            const parentIdx = series.path.lastIndexOf('.');
+            if (parentIdx > 0) {
+                addCandidate(series.path.slice(0, parentIdx), allSelfContext);
+            }
+        });
+        const candidates = Array.from(subscriptionCandidates.entries()).map(([path, meta]) => ({
+            path,
+            allSelfContext: meta.allSelfContext
+        }));
+        candidates.forEach(candidate => {
+            try {
+                const bus = candidate.allSelfContext && typeof streamBundle.getSelfBus === 'function'
+                    ? streamBundle.getSelfBus(candidate.path)
+                    : streamBundle.getBus(candidate.path);
+                if (!bus || typeof bus.onValue !== 'function') {
+                    return;
+                }
+                const unsubscribe = bus.onValue((sample) => {
+                    try {
+                        const count = historySeries.recordFromSignalKSample(sample);
+                        if (count > 0) {
+                            // server.debug(`[SERIES CAPTURE] path=${candidate.path} recorded=${count}`);
+                        }
+                    }
+                    catch (error) {
+                        server.error(`[SERIES CAPTURE] failed to record sample path=${candidate.path}: ${String(error.message || error)}`);
+                    }
+                });
+                if (typeof unsubscribe === 'function') {
+                    streamUnsubscribes.push(unsubscribe);
+                }
+            }
+            catch (error) {
+                server.error(`[SERIES CAPTURE] failed to subscribe path=${candidate.path}: ${String(error.message || error)}`);
+            }
+        });
+        // server.debug(`[SERIES CAPTURE] activePathSubscriptions=${candidates.length}`);
+    }
+    function startStorageFlushTimer(intervalMs) {
+        if (storageFlushTimer) {
+            clearInterval(storageFlushTimer);
+            storageFlushTimer = null;
+        }
+        if (!storageService.isSqliteEnabled()) {
+            return;
+        }
+        storageFlushTimer = setInterval(() => {
+            void storageService.flush()
+                .catch(error => {
+                server.error(`[SERIES STORAGE] flush failed: ${String(error.message || error)}`);
+            });
+        }, intervalMs);
+        storageFlushTimer.unref?.();
+    }
+    let modeConfig = null;
+    const plugin = {
+        id: 'kip',
+        name: 'KIP',
+        description: 'KIP server plugin',
+        start: async (settings) => {
+            server.debug('[KIP][LIFECYCLE] start');
+            modeConfig = resolveHistoryModeConfig(settings);
+            // Overwrite runtime-detected properties in modeConfig
+            modeConfig.nodeSqliteAvailable = await detectSqliteRuntime();
+            if (!modeConfig.nodeSqliteAvailable) {
+                server.error(`[KIP][RUNTIME] node:sqlite unavailable. ${runtimeSqliteUnavailableMessage}`);
+            }
+            storageService.setRuntimeAvailability(modeConfig.nodeSqliteAvailable, runtimeSqliteUnavailableMessage ?? undefined);
+            logRuntimeDependencyVersions();
+            logOperationalMode('start-configured');
+            const needsSqlite = (modeConfig.historySeriesServiceEnabled || modeConfig.registerAsHistoryApiProvider) && modeConfig.nodeSqliteAvailable;
+            if (needsSqlite) {
+                storageService.setLogger({
+                    debug: (msg) => server.debug(msg),
+                    error: (msg) => server.error(msg)
+                });
+                const storageConfig = storageService.configure();
+                server.debug(`[KIP][STORAGE] config engine=${storageConfig.engine} db=${storageConfig.databaseFile} flushMs=${storageConfig.flushIntervalMs}`);
+                historySeries.setSampleSink(sample => {
+                    storageService.enqueueSample(sample);
+                });
+                sqliteInitializationPromise = storageService.initialize();
+                void sqliteInitializationPromise.then((ready) => {
+                    server.debug(`[KIP][STORAGE] sqliteReady=${ready}`);
+                    if (ready && storageService.isSqliteEnabled()) {
+                        if (modeConfig && modeConfig.historySeriesServiceEnabled) {
+                            void storageService.getSeriesDefinitions()
+                                .then((storedSeries) => {
+                                if (storedSeries.length > 0) {
+                                    historySeries.reconcileSeries(storedSeries);
+                                    rebuildSeriesCaptureSubscriptions();
+                                }
+                                startStorageFlushTimer(storageConfig.flushIntervalMs);
+                                logOperationalMode('sqlite-ready');
+                                server.setPluginStatus(`Providing: Remote Control${historyApiProviderRegistered ? ', History service' : ', No History service'}${storedSeries.length > 0 ? `, ${storedSeries.length} Time-Series` : ', No Time-Series'}.`);
+                            })
+                                .catch((loadError) => {
+                                server.error(`[SERIES STORAGE] failed to load persisted series: ${String(loadError.message || loadError)}`);
+                                startStorageFlushTimer(storageConfig.flushIntervalMs);
+                                logOperationalMode('sqlite-ready-series-load-failed');
+                                server.setPluginStatus(`Providing: Remote Control${historyApiProviderRegistered ? ', History service' : ', No History service'}, No Time-Series.`);
+                            });
+                        }
+                        else {
+                            historySeries.reconcileSeries([]);
+                            stopSeriesCapture();
+                            startStorageFlushTimer(storageConfig.flushIntervalMs);
+                            logOperationalMode('sqlite-ready-series-disabled');
+                            server.setPluginStatus(`Providing: Remote Control${historyApiProviderRegistered ? ', History service' : ', No History service'}, No Time-Series.`);
+                        }
+                        return;
+                    }
+                    if (storageFlushTimer) {
+                        clearInterval(storageFlushTimer);
+                        storageFlushTimer = null;
+                    }
+                    const initError = storageService.getLastInitError();
+                    if (initError) {
+                        server.setPluginError(`node:sqlite unavailable. ${initError}`);
+                        logOperationalMode('sqlite-unavailable');
+                        server.setPluginStatus(`Providing: Remote Control${historyApiProviderRegistered ? ', History service' : ', No History service'}, No Time-Series.`);
+                    }
+                });
+                if (retentionSweepTimer) {
+                    clearInterval(retentionSweepTimer);
+                }
+                retentionSweepTimer = setInterval(() => {
+                    try {
+                        if (storageService.isSqliteReady()) {
+                            const lifecycleToken = storageService.getLifecycleToken();
+                            void storageService.pruneExpiredSamples(Date.now(), lifecycleToken)
+                                .then(removedPersistedRows => {
+                                if (removedPersistedRows > 0) {
+                                    server.debug(`[KIP][RETENTION] pruneExpired removedRows=${removedPersistedRows}`);
+                                }
+                                return storageService.pruneOrphanedSamples(lifecycleToken)
+                                    .then(removedOrphanRows => {
+                                    if (removedOrphanRows > 0) {
+                                        server.debug(`[KIP][RETENTION] pruneOrphaned removedRows=${removedOrphanRows}`);
+                                    }
+                                });
+                            })
+                                .catch(error => {
+                                server.error(`[SERIES RETENTION] node:sqlite Prune failed: ${String(error.message || error)}`);
+                            });
+                        }
+                    }
+                    catch (error) {
+                        server.error(`[SERIES RETENTION] node:sqlite sweep failed: ${String(error.message || error)}`);
+                    }
+                }, 60 * 60_000);
+                retentionSweepTimer.unref?.();
+                rebuildSeriesCaptureSubscriptions();
+            }
+            else {
+                if (modeConfig && !modeConfig.nodeSqliteAvailable && (modeConfig.historySeriesServiceEnabled || modeConfig.registerAsHistoryApiProvider)) {
+                    server.setPluginStatus(getSqliteUnavailableMessage());
+                }
+                server.debug('[KIP][STORAGE] sqlite init skipped reason=config-disabled-or-runtime');
+                sqliteInitializationPromise = null;
+                stopSeriesCapture();
+            }
+            if (server.registerPutHandler) {
+                server.debug(`[KIP][COMMAND] registerPutHandlers context=${PUT_CONTEXT}`);
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.SET_DISPLAY, (context, path, value) => {
+                    server.debug(`[KIP][COMMAND] putHandlerHit command=${COMMAND_PATHS.SET_DISPLAY} path=${String(path)} context=${String(context)}`);
+                    void context;
+                    void path;
+                    return handleSetDisplay(value);
+                }, plugin.id);
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.SET_SCREEN_INDEX, (context, path, value) => {
+                    server.debug(`[KIP][COMMAND] putHandlerHit command=${COMMAND_PATHS.SET_SCREEN_INDEX} path=${String(path)} context=${String(context)}`);
+                    void context;
+                    void path;
+                    return handleScreenWrite(value, 'screenIndex');
+                }, plugin.id);
+                server.registerPutHandler(PUT_CONTEXT, COMMAND_PATHS.REQUEST_ACTIVE_SCREEN, (context, path, value) => {
+                    server.debug(`[KIP][COMMAND] putHandlerHit command=${COMMAND_PATHS.REQUEST_ACTIVE_SCREEN} path=${String(path)} context=${String(context)}`);
+                    void context;
+                    void path;
+                    return handleScreenWrite(value, 'activeScreen');
+                }, plugin.id);
+            }
+            registerHistoryProvider();
+            logOperationalMode('post-provider-registration');
+            server.setPluginStatus(`Starting...`);
+        },
+        stop: () => {
+            server.debug('[KIP][LIFECYCLE] stop');
+            stopSeriesCapture();
+            if (retentionSweepTimer) {
+                clearInterval(retentionSweepTimer);
+                retentionSweepTimer = null;
+            }
+            if (storageFlushTimer) {
+                clearInterval(storageFlushTimer);
+                storageFlushTimer = null;
+            }
+            const storageLifecycleToken = storageService.getLifecycleToken();
+            void storageService.flush(storageLifecycleToken)
+                .catch(() => undefined)
+                .then(() => storageService.close(storageLifecycleToken))
+                .catch(() => undefined);
+            const serverWithHistoryApi = server;
+            const unregisterHistoryApiProvider = typeof serverWithHistoryApi.unregisterHistoryApiProvider === 'function'
+                ? serverWithHistoryApi.unregisterHistoryApiProvider.bind(serverWithHistoryApi)
+                : (typeof serverWithHistoryApi.history?.unregisterHistoryApiProvider === 'function'
+                    ? serverWithHistoryApi.history.unregisterHistoryApiProvider.bind(serverWithHistoryApi.history)
+                    : null);
+            if (unregisterHistoryApiProvider) {
+                unregisterHistoryApiProvider();
+            }
+            historyApiProviderRegistered = false;
+            sqliteInitializationPromise = null;
+            const msg = 'Stopped.';
+            server.setPluginStatus(msg);
+        },
+        schema: () => {
+            // Return schema with live modeConfig values
+            const schema = JSON.parse(JSON.stringify(CONFIG_SCHEMA));
+            if (schema && schema.properties && modeConfig) {
+                if (typeof modeConfig.nodeSqliteAvailable === 'boolean') {
+                    schema.properties.nodeSqliteAvailable.default = modeConfig.nodeSqliteAvailable;
+                }
+                if (typeof modeConfig.historySeriesServiceEnabled === 'boolean') {
+                    schema.properties.historySeriesServiceEnabled.default = modeConfig.historySeriesServiceEnabled;
+                }
+                if (typeof modeConfig.registerAsHistoryApiProvider === 'boolean') {
+                    schema.properties.registerAsHistoryApiProvider.default = modeConfig.registerAsHistoryApiProvider;
+                }
+            }
+            return schema;
+        },
+        registerWithRouter(router) {
+            server.debug(`[KIP][ROUTES] register displays=${API_PATHS.DISPLAYS} instance=${API_PATHS.INSTANCE} screenIndex=${API_PATHS.SCREEN_INDEX} activeScreen=${API_PATHS.ACTIVATE_SCREEN}`);
+            // Validate/normalize :displayId where present
+            router.param('displayId', (req, res, next, displayId) => {
+                logAuthTrace(req, 'router.param:displayId:entry');
+                if (displayId == null)
+                    return sendFail(res, 400, 'Missing displayId parameter');
+                try {
+                    let id = String(displayId);
+                    // Decode percent-encoding if present
+                    try {
+                        id = decodeURIComponent(id);
+                    }
+                    catch {
+                        // ignore decode errors, keep original id
+                    }
+                    // If someone sent JSON as the path segment, try to recover {"displayId":"..."}
+                    if (id.trim().startsWith('{')) {
+                        try {
+                            const parsed = JSON.parse(id);
+                            if (parsed && typeof parsed.displayId === 'string') {
+                                id = parsed.displayId;
+                            }
+                            else {
+                                return sendFail(res, 400, 'Invalid displayId format in JSON');
+                            }
+                        }
+                        catch {
+                            return sendFail(res, 400, 'Invalid displayId JSON');
+                        }
+                    }
+                    // Basic safety: allow UUID-like strings (alphanum + dash)
+                    if (!/^[A-Za-z0-9-]+$/.test(id)) {
+                        return sendFail(res, 400, 'Invalid displayId format');
+                    }
+                    req.displayId = id;
+                    server.debug(`[KIP][AUTH] displayIdNormalized value=${id}`);
+                    next();
+                }
+                catch {
+                    server.error(`[AUTH TRACE] router.param:displayId:failed rawDisplayId=${String(displayId)}`);
+                    return sendFail(res, 400, 'Missing or invalid displayId parameter');
+                }
+            });
+            router.put(`${API_PATHS.INSTANCE}`, async (req, res) => {
+                logAuthTrace(req, 'route:PUT:INSTANCE:entry');
+                server.debug(`[KIP][ROUTE] method=PUT path=${API_PATHS.INSTANCE} params=${JSON.stringify(req.params)} body=${JSON.stringify(req.body)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleSetDisplay({ displayId, display: req.body ?? null });
+                    return sendActionAsRest(res, result);
+                }
+                catch (error) {
+                    const msg = `HandleMessage failed with errors!`;
+                    server.setPluginError(msg);
+                    server.error(`Error in HandleMessage: ${error}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.put(`${API_PATHS.SCREEN_INDEX}`, async (req, res) => {
+                logAuthTrace(req, 'route:PUT:SCREEN_INDEX:entry');
+                server.debug(`[KIP][ROUTE] method=PUT path=${API_PATHS.SCREEN_INDEX} params=${JSON.stringify(req.params)} body=${JSON.stringify(req.body)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleScreenWrite({
+                        displayId,
+                        screenIdx: req.body?.screenIdx !== undefined ? req.body.screenIdx : null
+                    }, 'screenIndex');
+                    return sendActionAsRest(res, result);
+                }
+                catch (error) {
+                    const msg = `HandleMessage failed with errors!`;
+                    server.setPluginError(msg);
+                    server.error(`Error in HandleMessage: ${error}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.put(`${API_PATHS.ACTIVATE_SCREEN}`, async (req, res) => {
+                logAuthTrace(req, 'route:PUT:ACTIVATE_SCREEN:entry');
+                server.debug(`[KIP][ROUTE] method=PUT path=${API_PATHS.ACTIVATE_SCREEN} params=${JSON.stringify(req.params)} body=${JSON.stringify(req.body)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const result = handleScreenWrite({
+                        displayId,
+                        screenIdx: req.body?.screenIdx !== undefined ? req.body.screenIdx : null
+                    }, 'activeScreen');
+                    return sendActionAsRest(res, result);
+                }
+                catch (error) {
+                    const msg = `HandleMessage failed with errors!`;
+                    server.setPluginError(msg);
+                    server.error(`Error in HandleMessage: ${error}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(API_PATHS.DISPLAYS, (req, res) => {
+                server.debug(`[KIP][ROUTE] method=GET path=${API_PATHS.DISPLAYS} params=${JSON.stringify(req.params)}`);
+                try {
+                    const displays = getAvailableDisplays();
+                    const items = displays && typeof displays === 'object'
+                        ? Object.entries(displays)
+                            .filter(([, v]) => v && typeof v === 'object')
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            .map(([displayId, v]) => ({
+                            displayId,
+                            displayName: v?.value?.displayName ?? null
+                        }))
+                        : [];
+                    server.debug(`[KIP][DISPLAYS] raw=${JSON.stringify(displays)}`);
+                    server.debug(`[KIP][DISPLAYS] count=${items.length} items=${JSON.stringify(items)}`);
+                    return res.status(200).json(items);
+                }
+                catch (error) {
+                    server.error(`Error reading displays: ${String(error.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(`${API_PATHS.INSTANCE}`, (req, res) => {
+                server.debug(`[KIP][ROUTE] method=GET path=${API_PATHS.INSTANCE} params=${JSON.stringify(req.params)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const node = getDisplaySelfPath(displayId);
+                    if (node === undefined) {
+                        return sendFail(res, 404, `Display ${displayId} not found`);
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const screens = node?.value?.screens ?? null;
+                    return sendOk(res, screens);
+                }
+                catch (error) {
+                    server.error(`Error reading display ${req.params?.displayId}: ${String(error.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(`${API_PATHS.SCREEN_INDEX}`, (req, res) => {
+                server.debug(`[KIP][ROUTE] method=GET path=${API_PATHS.SCREEN_INDEX} params=${JSON.stringify(req.params)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const node = getDisplaySelfPath(displayId, 'screenIndex');
+                    if (node === undefined) {
+                        return sendFail(res, 404, `Active screen for display Id ${displayId} not found in path`);
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const idx = node?.value ?? null;
+                    return sendOk(res, idx);
+                }
+                catch (error) {
+                    server.error(`Error reading activeScreen for ${req.params?.displayId}: ${String(error.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(`${API_PATHS.ACTIVATE_SCREEN}`, (req, res) => {
+                server.debug(`[KIP][ROUTE] method=GET path=${API_PATHS.ACTIVATE_SCREEN} params=${JSON.stringify(req.params)}`);
+                try {
+                    const displayId = req.displayId;
+                    if (!displayId) {
+                        return sendFail(res, 400, 'Missing displayId parameter');
+                    }
+                    const node = getDisplaySelfPath(displayId, 'activeScreen');
+                    if (node === undefined) {
+                        return sendFail(res, 404, `Change display screen Id ${displayId} not found in path`);
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const idx = node?.value ?? null;
+                    return sendOk(res, idx);
+                }
+                catch (error) {
+                    server.error(`Error reading activeScreen for ${req.params?.displayId}: ${String(error.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(API_PATHS.SERIES, async (req, res) => {
+                server.debug(`[KIP][ROUTE] method=GET path=${API_PATHS.SERIES} params=${JSON.stringify(req.params)}`);
+                try {
+                    if (!ensureHistorySeriesServiceEnabledForRequest(res)) {
+                        return;
+                    }
+                    if (!(await ensureSqliteReadyForRequest(res))) {
+                        return;
+                    }
+                    return sendOk(res, historySeries.listSeries());
+                }
+                catch (error) {
+                    server.error(`Error reading series: ${String(error.message || error)}`);
+                    const mapped = getRouteError(error, 'Failed to read series');
+                    return sendFail(res, mapped.statusCode, mapped.message);
+                }
+            });
+            router.put(API_PATHS.SERIES_INSTANCE, async (req, res) => {
+                server.debug(`[KIP][ROUTE] method=PUT path=${API_PATHS.SERIES_INSTANCE} params=${JSON.stringify(req.params)} body=${JSON.stringify(req.body)}`);
+                try {
+                    if (!ensureHistorySeriesServiceEnabledForRequest(res)) {
+                        return;
+                    }
+                    if (!(await ensureSqliteReadyForRequest(res))) {
+                        return;
+                    }
+                    const seriesId = String(req.params.seriesId ?? '').trim();
+                    if (!seriesId) {
+                        return sendFail(res, 400, 'Missing seriesId parameter');
+                    }
+                    const payload = (req.body ?? {});
+                    const previous = findSeriesById(seriesId);
+                    const next = historySeries.upsertSeries({
+                        ...payload,
+                        seriesId,
+                        datasetUuid: String(payload.datasetUuid ?? seriesId)
+                    });
+                    try {
+                        await storageService.upsertSeriesDefinition(next);
+                    }
+                    catch (storageError) {
+                        if (previous) {
+                            historySeries.upsertSeries(previous);
+                        }
+                        else {
+                            historySeries.deleteSeries(seriesId);
+                        }
+                        throw storageError;
+                    }
+                    rebuildSeriesCaptureSubscriptions();
+                    return sendOk(res, next);
+                }
+                catch (error) {
+                    server.error(`Error writing series: ${String(error.message || error)}`);
+                    const mapped = getRouteError(error, 'Failed to write series');
+                    return sendFail(res, mapped.statusCode, mapped.message);
+                }
+            });
+            router.delete(API_PATHS.SERIES_INSTANCE, async (req, res) => {
+                server.debug(`[KIP][ROUTE] method=DELETE path=${API_PATHS.SERIES_INSTANCE} params=${JSON.stringify(req.params)}`);
+                try {
+                    if (!ensureHistorySeriesServiceEnabledForRequest(res)) {
+                        return;
+                    }
+                    if (!(await ensureSqliteReadyForRequest(res))) {
+                        return;
+                    }
+                    const seriesId = String(req.params.seriesId ?? '').trim();
+                    if (!seriesId) {
+                        return sendFail(res, 400, 'Missing seriesId parameter');
+                    }
+                    const previous = findSeriesById(seriesId);
+                    if (!previous) {
+                        return sendFail(res, 404, `Series ${seriesId} not found`);
+                    }
+                    await storageService.deleteSeriesDefinition(seriesId);
+                    historySeries.deleteSeries(seriesId);
+                    rebuildSeriesCaptureSubscriptions();
+                    return sendOk(res, { state: 'SUCCESS', statusCode: 200 });
+                }
+                catch (error) {
+                    server.error(`Error deleting series: ${String(error.message || error)}`);
+                    const mapped = getRouteError(error, 'Failed to delete series');
+                    return sendFail(res, mapped.statusCode, mapped.message);
+                }
+            });
+            router.post(API_PATHS.SERIES_RECONCILE, async (req, res) => {
+                server.debug(`[KIP][ROUTE] method=POST path=${API_PATHS.SERIES_RECONCILE} body=${JSON.stringify(req.body)}`);
+                try {
+                    if (!ensureHistorySeriesServiceEnabledForRequest(res)) {
+                        return;
+                    }
+                    if (!(await ensureSqliteReadyForRequest(res))) {
+                        return;
+                    }
+                    const payload = req.body;
+                    if (!Array.isArray(payload)) {
+                        return sendFail(res, 400, 'Body must be an array of series definitions');
+                    }
+                    const simulated = new history_series_service_1.HistorySeriesService(() => Date.now(), typeof server.selfId === 'string' && server.selfId.trim().length > 0 ? `vessels.${server.selfId.trim()}` : null);
+                    const currentSeries = mergeSeriesDefinitions([
+                        ...(await storageService.getSeriesDefinitions()),
+                        ...historySeries.listSeries()
+                    ]);
+                    currentSeries.forEach(series => {
+                        simulated.upsertSeries(series);
+                    });
+                    const scopedPayload = payload.map(series => ({
+                        ...series
+                    }));
+                    const isBatteryDiscoveryUnavailable = resolveBmsBatteryIdsFromSelfPath().length === 0;
+                    const preservedBmsSeries = isBatteryDiscoveryUnavailable
+                        ? scopedPayload
+                            .filter(history_series_service_1.isKipTemplateSeriesDefinition)
+                            .flatMap(series => currentSeries.filter(current => current.ownerWidgetUuid === series.ownerWidgetUuid && (0, history_series_service_1.isKipConcreteSeriesDefinition)(current) && current.seriesId !== series.seriesId))
+                        : [];
+                    const expandedPayload = mergeSeriesDefinitions([
+                        ...expandTemplateSeriesDefinitions(scopedPayload, currentSeries),
+                        ...preservedBmsSeries
+                    ]);
+                    const result = simulated.reconcileSeries(expandedPayload);
+                    const nextSeries = simulated.listSeries();
+                    await storageService.replaceSeriesDefinitions(nextSeries);
+                    const seriesOutsideScope = historySeries.listSeries();
+                    historySeries.reconcileSeries([...seriesOutsideScope, ...nextSeries]);
+                    server.debug(`[KIP][SERIES_RECONCILE] created=${result.created} updated=${result.updated} deleted=${result.deleted} total=${result.total}`);
+                    rebuildSeriesCaptureSubscriptions();
+                    return sendOk(res, result);
+                }
+                catch (error) {
+                    server.error(`Error reconciling series: ${String(error.message || error)}`);
+                    const mapped = getRouteError(error, 'Failed to reconcile series');
+                    return sendFail(res, mapped.statusCode, mapped.message);
+                }
+            });
+            // List all registered routes for debugging
+            if (router.stack) {
+                router.stack.forEach((layer) => {
+                    if (layer.route && layer.route.path) {
+                        server.debug(`[KIP][ROUTES] registered method=${layer.route.stack[0].method.toUpperCase()} path=${layer.route.path}`);
+                    }
+                });
+            }
+            server.setPluginStatus(`Providing remote display screen control and history series API`);
+        },
+        getOpenApi: () => mutableOpenApi
+    };
+    return plugin;
+};
+const startWithHooks = start;
+startWithHooks.getSqliteModule = defaultGetSqliteModule;
+module.exports = start;