@juspay/neurolink 12.20.0 → 12.20.2

package/dist/cli/commands/proxy.js

@@ -1,4 +1,4 @@
-import { initializeProxyOtelLogs, routeProxyConsoleToOtel, flushProxyOtelLogs, shutdownProxyOtelLogs, isProxyOtelOnly, withProxyOtelLogShutdown, } from "../../proxy/otelLogSink.js";
+import { initializeProxyOtelLogs, routeProxyConsoleToOtel, shutdownProxyOtelLogs, isProxyOtelOnly, withProxyOtelLogShutdown, } from "../../proxy/otelLogSink.js";
 import { registerCliShutdownOwner } from "../lifecycle.js";
 import { writeFileAtomic } from "../proxy-clients/snapshot.js";
 import { spawn } from "node:child_process";
@@ -35,8 +35,8 @@ import { isProxyAuxiliaryRequest } from "../../proxy/proxyRequestKind.js";
 import { spawnProxySocketWorker } from "../../proxy/rollingWorkerProcess.js";
 import { PROXY_ROLLING_SUPERVISOR_ENV, PROXY_SOCKET_WORKER_ENV, } from "../../proxy/rollingWorkerProtocol.js";
 import { attachSocketWorkerProcess } from "../../proxy/socketWorkerRuntime.js";
-import { parseProxyRuntimeActivity, isProxyUpdateOwnerCurrent, shouldRefreshStaleSupervisor, waitForProxyUpdateWindow, } from "../../proxy/updateCoordinator.js";
-import { abandonPendingUpdate, clearUpdateDeferral, isVersionSuppressed, loadUpdateState, recordCheck, recordSuccessfulUpdate, recordUpdateDeferred, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../proxy/updateState.js";
+import { isSameProxyServingWorker, parseProxyServingWorkerIdentity, parseProxyRuntimeActivity, isProxyUpdateOwnerCurrent, shouldRefreshStaleSupervisor, waitForProxyUpdateWindow, } from "../../proxy/updateCoordinator.js";
+import { abandonPendingUpdate, clearUpdateDeferral, isVersionSuppressed, loadUpdateState, recordCheck, recordCheckFailure, recordSuccessfulUpdate, recordUpdateDeferred, recordUpdateFailure, recordUpdateInstalled, suppressVersion, } from "../../proxy/updateState.js";
 import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../proxy/proxyEnv.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -542,7 +542,7 @@ async function fetchProxyHealthVersion(host, port) {
     }
 }
 /** Read both serving generations so an updated worker cannot hide a stale parent. */
-async function fetchProxyRuntimeVersions(host, port) {
+async function fetchProxyRuntimeVersions(host, port, rollingSupervisor = false) {
     try {
         const response = await fetch(`http://${host}:${port}/status`, {
             headers: { connection: "close" },
@@ -552,10 +552,12 @@ async function fetchProxyRuntimeVersions(host, port) {
             return {};
         }
         const data = (await response.json());
+        const workerIdentity = parseProxyServingWorkerIdentity(data, rollingSupervisor);
         return {
             ...(typeof data.version === "string"
                 ? { workerVersion: data.version }
                 : {}),
+            ...(workerIdentity ? { workerIdentity } : {}),
             ...(typeof data.autoUpdate?.supervisorVersion === "string"
                 ? { supervisorVersion: data.autoUpdate.supervisorVersion }
                 : {}),
@@ -574,11 +576,17 @@ async function fetchProxyRuntimeVersions(host, port) {
  * signal SIGUSR2) and wait until the supervisor actually serves that version
  * again. Returns false if it never reports the running version healthy in time.
  */
-async function activateRollbackVersion(host, port, parentPid, runningVersion, timeoutMs) {
+async function activateRollbackVersion(host, port, parentPid, runningVersion, timeoutMs, isCurrentOwner) {
+    if (!isCurrentOwner()) {
+        return false;
+    }
     recordUpdateInstalled(runningVersion);
     try {
         const start = Date.now();
         while (Date.now() - start < timeoutMs) {
+            if (!isCurrentOwner()) {
+                return false;
+            }
             try {
                 process.kill(parentPid, "SIGUSR2");
             }
@@ -626,7 +634,7 @@ async function setProxyUpdateDrain(host, port, draining, supervisorRefresh = fal
             body: JSON.stringify({
                 action: draining
                     ? supervisorRefresh
-                        ? "drain_for_supervisor_refresh"
+                        ? "fence_for_supervisor_refresh"
                         : "drain"
                     : "resume",
             }),
@@ -1555,21 +1563,31 @@ export async function createProxyStartApp(params) {
             .json()
             .catch(() => ({ action: undefined }));
         if (payload.action === "drain" ||
-            payload.action === "drain_for_supervisor_refresh") {
+            payload.action === "drain_for_supervisor_refresh" ||
+            payload.action === "fence_for_supervisor_refresh") {
             // A rolling worker must keep admitting until the supervisor has a ready
             // replacement. The legacy global drain can otherwise strand the listener
             // behind maintenance responses when its caller stalls or disappears.
             if (isProxySocketWorkerProcess() &&
-                payload.action !== "drain_for_supervisor_refresh") {
+                payload.action !== "drain_for_supervisor_refresh" &&
+                payload.action !== "fence_for_supervisor_refresh") {
                 return c.json({
                     error: "rolling_restart_required",
                     message: "Use neurolink proxy restart; global update drain is disabled for rolling workers.",
                 }, 409);
             }
+            // No await between the activity check and fence: an HTTP request cannot
+            // enter this worker between the idle observation and admission closure.
+            // The updater separately verifies all supervisor generations are settled.
+            if (payload.action === "fence_for_supervisor_refresh" &&
+                getProxyActivitySnapshot().activeRequests !== 0) {
+                return c.json({ error: "proxy_busy", draining: false }, 409);
+            }
             if (!markProxyDrainingForUpdate(readiness)) {
                 return c.json({ error: "proxy_not_ready" }, 409);
             }
-            if (payload.action === "drain_for_supervisor_refresh") {
+            if (payload.action === "drain_for_supervisor_refresh" ||
+                payload.action === "fence_for_supervisor_refresh") {
                 // A crashed updater must not strand the current rolling worker in
                 // maintenance mode. A successful launchd refresh replaces this process.
                 scheduleSupervisorRefreshResume(90 * 1000);
@@ -2243,6 +2261,8 @@ export async function createProxyStartApp(params) {
                     : "restart",
                 deferredUpdate: updateState?.deferredUpdate ?? null,
                 lastCheckAt: updateState?.lastCheckAt ?? null,
+                lastCheckAttemptAt: updateState?.lastCheckAttemptAt ?? null,
+                lastCheckError: updateState?.lastCheckError ?? null,
                 lastUpdateAt: updateState?.lastUpdateAt ?? null,
                 lastUpdateVersion: updateState?.lastUpdateVersion ?? null,
                 lastFailure: updateState?.lastFailure
@@ -2583,7 +2603,6 @@ function registerProxyShutdownHandlers(params) {
         try {
             const { flushOpenTelemetry, shutdownOpenTelemetry } = await import("../../services/server/ai/observability/instrumentation.js");
             await withShutdownDeadline((async () => {
-                await flushProxyOtelLogs();
                 await shutdownProxyOtelLogs();
                 await flushOpenTelemetry();
                 await shutdownOpenTelemetry();
@@ -2990,7 +3009,6 @@ async function runLaunchdProxySupervisor(argv, spinner) {
         if (otelInitialized) {
             await cleanup(async () => {
                 await flushProxyLifecycleEvents().catch(reportCleanupFailure);
-                await flushProxyOtelLogs().catch(reportCleanupFailure);
                 await shutdownProxyOtelLogs();
             }, PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS, "supervisor telemetry shutdown deadline exceeded");
         }
@@ -3585,6 +3603,8 @@ export const proxyStatusCommand = {
                 latestVersion: updateState?.lastCheckVersion || null,
                 lastDetectedVersion: updateState?.lastCheckVersion || null,
                 lastCheckAt: updateState?.lastCheckAt ?? null,
+                lastCheckAttemptAt: updateState?.lastCheckAttemptAt ?? null,
+                lastCheckError: updateState?.lastCheckError ?? null,
                 installedVersion: updateState?.installedVersion ??
                     updateState?.lastUpdateVersion ??
                     null,
@@ -4048,16 +4068,68 @@ export const proxyGuardCommand = {
             updateInProgress = true;
             let updateVersion = runningVersion;
             let drainActive = false;
-            let previousPackage = readProxyPackageSelection(PROXY_PACKAGES_DIR);
-            if (previousPackage?.version !== runningVersion) {
-                previousPackage = readProxyPackageSelection(PROXY_PACKAGES_DIR, true);
-            }
+            let previousPackage;
             let candidatePackage;
+            let servingWorkerIdentity;
+            let activatedWorkerIdentity;
+            const readPersistedServingIdentity = () => {
+                if (!servingWorkerIdentity) {
+                    return null;
+                }
+                if (rollingSupervisor) {
+                    const active = loadProxySupervisorState()?.rolling?.active;
+                    return active
+                        ? {
+                            version: active.version,
+                            pid: active.pid,
+                            generation: active.generation,
+                        }
+                        : null;
+                }
+                const state = loadProxyState();
+                return state?.pid
+                    ? {
+                        version: servingWorkerIdentity.version,
+                        pid: state.pid,
+                        generation: null,
+                    }
+                    : null;
+            };
+            const isCurrentUpdateAttemptOwner = () => {
+                if (!isCurrentUpdateOwner() || !servingWorkerIdentity) {
+                    return false;
+                }
+                const current = readPersistedServingIdentity();
+                return (isSameProxyServingWorker(servingWorkerIdentity, current) ||
+                    (activatedWorkerIdentity !== undefined &&
+                        isSameProxyServingWorker(activatedWorkerIdentity, current)));
+            };
             try {
+                // A rolling worker may have changed since this updater started. Never
+                // use startup identity to choose rollback or downgrade a serving worker.
+                const runtimeVersions = await fetchProxyRuntimeVersions(host, port, rollingSupervisor);
+                servingWorkerIdentity = runtimeVersions.workerIdentity;
+                const observedVersion = servingWorkerIdentity?.version;
+                if (!observedVersion) {
+                    persistUpdaterState("record unavailable runtime identity", () => recordCheckFailure("Serving worker version could not be verified"));
+                    scheduleUpdateRetry("runtime version probe incomplete", runningVersion);
+                    return;
+                }
+                runningVersion = observedVersion;
+                updateVersion = runningVersion;
+                previousPackage = readProxyPackageSelection(PROXY_PACKAGES_DIR);
+                if (previousPackage?.version !== runningVersion) {
+                    previousPackage = readProxyPackageSelection(PROXY_PACKAGES_DIR, true);
+                }
                 // Lazy-load update modules so they're only imported at check time
                 const { checkForUpdate } = await import("../../proxy/updateChecker.js");
                 // 1. Check for update
                 let result = await checkForUpdate(runningVersion);
+                if (result.checkSucceeded === false) {
+                    persistUpdaterState("record failed update check", () => recordCheckFailure(result.checkError ?? "Registry check failed"));
+                    scheduleUpdateRetry("registry check failed", runningVersion);
+                    return;
+                }
                 updateVersion = result.latestVersion;
                 persistUpdaterState("record update check", () => recordCheck(result.latestVersion));
                 let supervisorRefreshOnly = false;
@@ -4084,6 +4156,10 @@ export const proxyGuardCommand = {
                         persistUpdaterState("clear update deferral", () => clearUpdateDeferral());
                         return;
                     }
+                    // A stale registry mirror can report a lower version. Reconcile the
+                    // supervisor to the observed worker, never to that older registry row.
+                    result = { ...result, latestVersion: runningVersion };
+                    updateVersion = runningVersion;
                     logger.always(`[updater] worker v${runningVersion} is current; reconciling stale supervisor v${activeVersions.supervisorVersion}`);
                 }
                 const initiallyPendingRestart = loadUpdateState()?.pendingRestartVersion === result.latestVersion;
@@ -4100,7 +4176,20 @@ export const proxyGuardCommand = {
                 // Recheck the target before staging because discovery can be delayed.
                 let pendingRestart = initiallyPendingRestart;
                 if (!supervisorRefreshOnly) {
+                    const refreshedRuntime = await fetchProxyRuntimeVersions(host, port, rollingSupervisor);
+                    if (!servingWorkerIdentity ||
+                        !isSameProxyServingWorker(servingWorkerIdentity, refreshedRuntime.workerIdentity)) {
+                        // Another updater/manual rotation won while registry discovery was
+                        // pending. Restart discovery using that worker on the next tick.
+                        scheduleUpdateRetry("serving worker changed during discovery", runningVersion);
+                        return;
+                    }
                     const refreshedResult = await checkForUpdate(runningVersion);
+                    if (refreshedResult.checkSucceeded === false) {
+                        persistUpdaterState("record failed refreshed update check", () => recordCheckFailure(refreshedResult.checkError ?? "Registry check failed"));
+                        scheduleUpdateRetry("refreshed registry check failed", runningVersion);
+                        return;
+                    }
                     result = refreshedResult;
                     updateVersion = result.latestVersion;
                     persistUpdaterState("record refreshed update check", () => recordCheck(result.latestVersion));
@@ -4185,6 +4274,12 @@ export const proxyGuardCommand = {
                 if (!isCurrentUpdateOwner()) {
                     return;
                 }
+                const publicationRuntime = await fetchProxyRuntimeVersions(host, port, rollingSupervisor);
+                if (!servingWorkerIdentity ||
+                    !isSameProxyServingWorker(servingWorkerIdentity, publicationRuntime.workerIdentity)) {
+                    scheduleUpdateRetry("serving worker changed during staging", result.latestVersion);
+                    return;
+                }
                 // 4. Refresh and validate the stable trampoline. The plist already
                 // points at this path, so it must not be unloaded or rewritten here.
                 if (!supervisorRefreshOnly) {
@@ -4200,9 +4295,9 @@ export const proxyGuardCommand = {
                         }
                         if (previousPackage?.version === runningVersion &&
                             !pendingRestart) {
-                            selectProxyPackage(PROXY_PACKAGES_DIR, previousPackage, isCurrentUpdateOwner);
+                            selectProxyPackage(PROXY_PACKAGES_DIR, previousPackage, isCurrentUpdateAttemptOwner);
                         }
-                        writeTrampoline(candidatePackage, isCurrentUpdateOwner);
+                        writeTrampoline(candidatePackage, isCurrentUpdateAttemptOwner);
                         const validation = await validateInstalledVersion({
                             binPath: TRAMPOLINE_PATH,
                             expectedVersion: result.latestVersion,
@@ -4216,7 +4311,7 @@ export const proxyGuardCommand = {
                             persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "validation", message));
                             persistUpdaterState("abandon invalid pending update", () => abandonPendingUpdate(result.latestVersion));
                             if (previousPackage) {
-                                writeTrampoline(previousPackage, isCurrentUpdateOwner);
+                                writeTrampoline(previousPackage, isCurrentUpdateAttemptOwner);
                             }
                             scheduleUpdateRetry("transient candidate validation failure", result.latestVersion);
                             return;
@@ -4235,7 +4330,7 @@ export const proxyGuardCommand = {
                         persistUpdaterState("record update failure", () => recordUpdateFailure(result.latestVersion, "validation", message));
                         persistUpdaterState("abandon invalid pending update", () => abandonPendingUpdate(result.latestVersion));
                         if (previousPackage) {
-                            writeTrampoline(previousPackage, isCurrentUpdateOwner);
+                            writeTrampoline(previousPackage, isCurrentUpdateAttemptOwner);
                         }
                         scheduleUpdateRetry("candidate validation failed; restaging permitted", result.latestVersion);
                         return;
@@ -4297,16 +4392,28 @@ export const proxyGuardCommand = {
                 if (!isCurrentUpdateOwner()) {
                     return;
                 }
+                const activationRuntime = await fetchProxyRuntimeVersions(host, port, rollingSupervisor);
+                if (!servingWorkerIdentity ||
+                    !isSameProxyServingWorker(servingWorkerIdentity, activationRuntime.workerIdentity)) {
+                    scheduleUpdateRetry("serving worker changed before activation", result.latestVersion);
+                    return;
+                }
                 updateRestartInProgress = true;
                 if (rollingSupervisor) {
-                    const activeVersions = await fetchProxyRuntimeVersions(host, port);
+                    const activeVersions = await fetchProxyRuntimeVersions(host, port, true);
+                    if (!servingWorkerIdentity ||
+                        !isSameProxyServingWorker(servingWorkerIdentity, activeVersions.workerIdentity)) {
+                        updateRestartInProgress = false;
+                        scheduleUpdateRetry("serving worker changed at activation boundary", result.latestVersion);
+                        return;
+                    }
                     if (activeVersions.workerVersion === result.latestVersion) {
                         logger.always(`[updater] worker v${result.latestVersion} is already active; resuming supervisor refresh without another worker replacement`);
                     }
                     else {
                         logger.always(`[updater] requesting rolling activation of v${result.latestVersion}`);
                         try {
-                            if (!isCurrentUpdateOwner()) {
+                            if (!isCurrentUpdateAttemptOwner()) {
                                 updateRestartInProgress = false;
                                 return;
                             }
@@ -4358,6 +4465,14 @@ export const proxyGuardCommand = {
                         if (resp.ok) {
                             const data = (await resp.json());
                             if (data.version === result.latestVersion) {
+                                if (rollingSupervisor && servingWorkerIdentity) {
+                                    const observedRuntime = await fetchProxyRuntimeVersions(host, port, true);
+                                    if (observedRuntime.workerIdentity?.version ===
+                                        result.latestVersion &&
+                                        !isSameProxyServingWorker(servingWorkerIdentity, observedRuntime.workerIdentity)) {
+                                        activatedWorkerIdentity ??= observedRuntime.workerIdentity;
+                                    }
+                                }
                                 healthy = true;
                                 break;
                             }
@@ -4367,6 +4482,13 @@ export const proxyGuardCommand = {
                         /* retry */
                     }
                     if (rollingSupervisor) {
+                        const observedRuntime = await fetchProxyRuntimeVersions(host, port, true);
+                        if (observedRuntime.workerIdentity?.version ===
+                            result.latestVersion &&
+                            servingWorkerIdentity &&
+                            !isSameProxyServingWorker(servingWorkerIdentity, observedRuntime.workerIdentity)) {
+                            activatedWorkerIdentity ??= observedRuntime.workerIdentity;
+                        }
                         rollingFailure = await getRollingActivationFailure(host, port, result.latestVersion);
                         if (rollingFailure) {
                             break;
@@ -4380,6 +4502,7 @@ export const proxyGuardCommand = {
                         let lastRefreshDeferral = "";
                         const waitForSupervisorRefresh = async (quietWaitMs) => {
                             const window = await waitForProxyUpdateWindow({
+                                allowBusyDrain: false,
                                 quietThresholdMs: QUIET_THRESHOLD_MS,
                                 quietWaitMs,
                                 drainWaitMs: UPDATE_DRAIN_TIMEOUT_MS,
@@ -4416,7 +4539,9 @@ export const proxyGuardCommand = {
                             logger.always(`[updater] supervisor refresh deferred: ${refreshWindow.reason ?? "safe window unavailable"}`);
                             persistUpdaterState("record supervisor refresh deferral", () => recordUpdateDeferred(result.latestVersion, refreshWindow.reason === "drain_timeout"
                                 ? "drain_timeout"
-                                : "drain_unavailable", null));
+                                : refreshWindow.reason === "busy"
+                                    ? "waiting_for_quiet"
+                                    : "drain_unavailable", null));
                             updateRestartInProgress = false;
                             scheduleUpdateRetry("supervisor refresh window unavailable", result.latestVersion);
                             return;
@@ -4425,7 +4550,21 @@ export const proxyGuardCommand = {
                             updateRestartInProgress = false;
                             return;
                         }
+                        const refreshIdentity = await fetchProxyRuntimeVersions(host, port, true);
+                        const allowedRefreshIdentity = servingWorkerIdentity &&
+                            (isSameProxyServingWorker(servingWorkerIdentity, refreshIdentity.workerIdentity) ||
+                                (activatedWorkerIdentity !== undefined &&
+                                    isSameProxyServingWorker(activatedWorkerIdentity, refreshIdentity.workerIdentity)));
+                        if (!allowedRefreshIdentity) {
+                            updateRestartInProgress = false;
+                            scheduleUpdateRetry("serving worker changed before supervisor refresh", result.latestVersion);
+                            return;
+                        }
                         logger.always(`[updater] refreshing launchd supervisor at v${result.latestVersion}`);
+                        if (!isCurrentUpdateAttemptOwner()) {
+                            updateRestartInProgress = false;
+                            return;
+                        }
                         const uid = process.getuid?.() ?? 501;
                         try {
                             execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/${PLIST_LABEL}`], { timeout: 10_000, stdio: "pipe" });
@@ -4473,7 +4612,6 @@ export const proxyGuardCommand = {
                     updateRetryAttempts = 0;
                     updateRetryVersion = null;
                     // The replacement proxy starts a worker running the new version.
-                    await flushProxyOtelLogs().catch(() => undefined);
                     await shutdownProxyOtelLogs().catch(() => undefined);
                     process.exit(0);
                 }
@@ -4488,12 +4626,20 @@ export const proxyGuardCommand = {
                             return;
                         }
                         try {
+                            const rollbackRuntime = await fetchProxyRuntimeVersions(host, port, true);
+                            const rollbackStillOwned = servingWorkerIdentity &&
+                                (isSameProxyServingWorker(servingWorkerIdentity, rollbackRuntime.workerIdentity) ||
+                                    (activatedWorkerIdentity !== undefined &&
+                                        isSameProxyServingWorker(activatedWorkerIdentity, rollbackRuntime.workerIdentity)));
+                            if (!rollbackStillOwned) {
+                                throw new Error("Serving worker identity changed; stale updater refused rollback");
+                            }
                             if (!previousPackage ||
                                 previousPackage.version !== runningVersion) {
                                 throw new Error("Previous validated package selection is unavailable");
                             }
                             logger.always(`[updater] restoring immutable package selection v${runningVersion}`);
-                            writeTrampoline(previousPackage, isCurrentUpdateOwner);
+                            writeTrampoline(previousPackage, isCurrentUpdateAttemptOwner);
                             const rollbackValidation = await validateInstalledVersion({
                                 binPath: TRAMPOLINE_PATH,
                                 expectedVersion: runningVersion,
@@ -4511,7 +4657,7 @@ export const proxyGuardCommand = {
                                 updateRestartInProgress = false;
                                 return;
                             }
-                            const rollbackActivated = await activateRollbackVersion(host, port, parentPid, runningVersion, UPDATE_TIMEOUT_MS);
+                            const rollbackActivated = await activateRollbackVersion(host, port, parentPid, runningVersion, UPDATE_TIMEOUT_MS, isCurrentUpdateAttemptOwner);
                             if (!rollbackActivated) {
                                 throw new Error(`supervisor did not report v${runningVersion} healthy within ${UPDATE_TIMEOUT_MS}ms after rollback`);
                             }

package/dist/cli/commands/telemetry.d.ts

@@ -10,7 +10,7 @@
  * - stats: Show token/cost stats
  */
 import type { CommandModule } from "yargs";
-import type { TelemetryStatusArgs as StatusArgs, TelemetryConfigureArgs as ConfigureArgs, TelemetryListExportersArgs as ListExportersArgs, TelemetryFlushArgs as FlushArgs, TelemetryStatsArgs as StatsArgs } from "../../types/index.js";
+import type { TelemetryStatusArgs as StatusArgs, TelemetryConfigureArgs as ConfigureArgs, TelemetryListExportersArgs as ListExportersArgs, TelemetryFlushArgs as FlushArgs, TelemetryStatsArgs as StatsArgs, TelemetryNativePrepareArgs, TelemetryNativeValidateArgs } from "../../types/index.js";
 /**
  * Telemetry Command Factory
  */
@@ -19,6 +19,9 @@ export declare class TelemetryCommandFactory {
      * Create the telemetry command group
      */
     static createTelemetryCommands(): CommandModule<object, object>;
+    /** Stage a native migration without modifying an installed service. */
+    static createNativePrepareCommand(): CommandModule<object, TelemetryNativePrepareArgs>;
+    static createNativeValidateCommand(): CommandModule<object, TelemetryNativeValidateArgs>;
     /**
      * Create the status subcommand
      */

package/dist/cli/commands/telemetry.js

@@ -16,6 +16,7 @@ import { NeuroLink } from "../../neurolink.js";
 import { flushOpenTelemetry } from "../../services/server/ai/observability/instrumentation.js";
 import { formatRow, formatCost } from "../utils/formatters.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
+import { prepareNativeTelemetry, validateNativeTelemetry, } from "../utils/nativeTelemetry.js";
 /**
  * Available exporter names
  */
@@ -49,6 +50,8 @@ export class TelemetryCommandFactory {
                     .command(TelemetryCommandFactory.createListExportersCommand())
                     .command(TelemetryCommandFactory.createFlushCommand())
                     .command(TelemetryCommandFactory.createStatsCommand())
+                    .command(TelemetryCommandFactory.createNativePrepareCommand())
+                    .command(TelemetryCommandFactory.createNativeValidateCommand())
                     .demandCommand(1, "Please specify a subcommand")
                     .strict();
             },
@@ -57,6 +60,116 @@ export class TelemetryCommandFactory {
             },
         };
     }
+    /** Stage a native migration without modifying an installed service. */
+    static createNativePrepareCommand() {
+        return {
+            command: "native-prepare",
+            describe: "Stage private durable/split collector files; never activate a service",
+            builder: (yargs) => yargs
+                .option("collectorConfig", {
+                alias: "collector-config",
+                type: "string",
+                demandOption: true,
+                describe: "Existing native collector YAML (read only)",
+            })
+                .option("output", {
+                type: "string",
+                demandOption: true,
+                describe: "New absolute staging directory; existing paths are refused",
+            })
+                .option("queueDirectory", {
+                alias: "queue-directory",
+                type: "string",
+                demandOption: true,
+                describe: "Planned private durable queue directory (not created)",
+            })
+                .option("compactionDirectory", {
+                alias: "compaction-directory",
+                type: "string",
+                demandOption: true,
+                describe: "Planned separate private compaction directory (not created)",
+            })
+                .option("bodyPort", {
+                alias: "body-port",
+                type: "number",
+                default: 14319,
+            })
+                .option("bodyStream", {
+                alias: "body-stream",
+                type: "string",
+                describe: "Separate body stream; defaults to <existing metadata stream>_bodies",
+            })
+                .option("metadataQueueMib", {
+                alias: "metadata-queue-mib",
+                type: "number",
+                default: 32,
+                describe: "Payload limit per metadata signal (three queues)",
+            })
+                .option("bodyQueueMib", {
+                alias: "body-queue-mib",
+                type: "number",
+                default: 256,
+            })
+                .option("diskQuotaMib", {
+                alias: "disk-quota-mib",
+                type: "number",
+                default: 1024,
+                describe: "Operator-managed volume quota to review; not applied by this command",
+            })
+                .option("metadataRetentionDays", {
+                alias: "metadata-retention-days",
+                type: "number",
+                default: 14,
+                describe: "Planned backend retention; not applied",
+            })
+                .option("bodyRetentionDays", {
+                alias: "body-retention-days",
+                type: "number",
+                default: 3,
+                describe: "Planned backend body retention; not applied",
+            }),
+            handler: async (args) => {
+                try {
+                    logger.always(JSON.stringify(await prepareNativeTelemetry(args), null, 2));
+                }
+                catch (error) {
+                    logger.error(error instanceof Error
+                        ? error.message
+                        : "Native telemetry preparation failed");
+                    process.exitCode = 1;
+                }
+            },
+        };
+    }
+    static createNativeValidateCommand() {
+        return {
+            command: "native-validate",
+            describe: "Validate staged profile using collector >= 0.160; never start or restart a service",
+            builder: (yargs) => yargs
+                .option("directory", {
+                type: "string",
+                demandOption: true,
+                describe: "Private directory produced by native-prepare",
+            })
+                .option("collectorBin", {
+                alias: "collector-bin",
+                type: "string",
+                demandOption: true,
+                describe: "Absolute path to trusted otelcol-contrib executable",
+            }),
+            handler: async (args) => {
+                try {
+                    logger.always(JSON.stringify(await validateNativeTelemetry(args), null, 2));
+                }
+                catch (error) {
+                    logger.error(error instanceof Error
+                        ? error.message
+                        : "Native telemetry validation failed");
+                    process.exitCode = 1;
+                }
+            },
+        };
+    }
     /**
      * Create the status subcommand
      */

package/dist/cli/utils/nativeTelemetry.d.ts

@@ -0,0 +1,19 @@
+import type { TelemetryNativePrepareArgs, TelemetryNativeValidateArgs } from "../../types/index.js";
+/** Produce new private files only. Existing config, services and queues are untouched. */
+export declare function prepareNativeTelemetry(args: TelemetryNativePrepareArgs): Promise<{
+    directory: string;
+    prepared: boolean;
+    activated: boolean;
+    metadataStream: string;
+    bodyStream: string;
+    pending: string[];
+}>;
+/** Runs only the collector's static validator, with test-owned temporary storage. */
+export declare function validateNativeTelemetry(args: TelemetryNativeValidateArgs): Promise<{
+    directory: string;
+    valid: boolean;
+    collectorVersion: string;
+    activated: boolean;
+    runtimeVerified: boolean;
+    pending: string[];
+}>;