@haystackeditor/cli 0.15.26 → 0.15.27

package/dist/commands/telemetry.js

@@ -0,0 +1,832 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+import fg from 'fast-glob';
+// @babel/core intentionally has no bundled declarations. Keep this small
+// build-transform boundary dynamic instead of leaking `any` into CLI contracts.
+const require = createRequire(import.meta.url);
+const babel = require('@babel/core');
+const INSTRUMENTED_MARKER = '__haystack_telemetry_instrumented_v1__';
+const INSTRUMENTED_MARKER_COMMENT = `/* ${INSTRUMENTED_MARKER} */`;
+const BOOTSTRAP_MARKER = '__haystack_telemetry_bootstrap_v1__';
+const BOOTSTRAP_MARKER_COMMENT = `/* ${BOOTSTRAP_MARKER} */`;
+const RUNTIME_DIRECTORY = '.haystack-telemetry';
+const RUNTIME_FILENAME = 'runtime.cjs';
+const RUNTIME_ESM_FILENAME = 'runtime.mjs';
+const MANIFEST_FILENAME = 'instrumentation.json';
+const RUNTIME_CONTROL_CHANNEL_PLACEHOLDER = '__HAYSTACK_TELEMETRY_CONTROL_CHANNEL__';
+const RUNTIME_INTEGRITY_PLACEHOLDER = '__HAYSTACK_TELEMETRY_RUNTIME_INTEGRITY__';
+const MANIFEST_SCHEMA_VERSION = 'haystack-node-telemetry-instrumentation-v3';
+const MAX_INSTRUMENTED_SITES = 50_000;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs'];
+const SAFE_SOURCE_PATH = /^[^#|\r\n]+$/;
+const SAFE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;
+function generatedBody(code) {
+    const body = code.startsWith('#!')
+        ? code.slice(code.indexOf('\n') + 1)
+        : code;
+    return body;
+}
+function hasGeneratedInstrumentation(code) {
+    const body = generatedBody(code);
+    return body.startsWith(INSTRUMENTED_MARKER_COMMENT) ||
+        body.startsWith(BOOTSTRAP_MARKER_COMMENT);
+}
+function hasGeneratedEntryBootstrap(code) {
+    // The bootstrap is inserted after directive prologues so a customer's
+    // `"use strict"` remains effective. It therefore need not be byte zero.
+    return generatedBody(code).includes(BOOTSTRAP_MARKER_COMMENT);
+}
+function normalizeLineEndings(value) {
+    return value.replace(/\r\n/g, '\n');
+}
+function normalizedPath(path) {
+    return path.split(sep).join('/');
+}
+function assertInside(root, candidate, label) {
+    const rel = relative(root, candidate);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`${label} must be inside ${root}`);
+    }
+}
+function shortHash(parts) {
+    const hash = createHash('sha256');
+    for (const part of parts)
+        hash.update(part).update('\0');
+    return hash.digest('hex').slice(0, 24);
+}
+function functionName(path) {
+    const node = path.node;
+    if (SAFE_IDENTIFIER.test(node.id?.name || ''))
+        return node.id.name;
+    if (SAFE_IDENTIFIER.test(node.key?.name || ''))
+        return node.key.name;
+    const parent = path.parentPath;
+    if (parent?.isVariableDeclarator() && SAFE_IDENTIFIER.test(parent.node.id?.name || ''))
+        return parent.node.id.name;
+    if (parent?.isObjectProperty() && SAFE_IDENTIFIER.test(parent.node.key?.name || ''))
+        return parent.node.key.name;
+    if (parent?.isAssignmentExpression() && SAFE_IDENTIFIER.test(parent.node.left?.property?.name || '')) {
+        return parent.node.left.property.name;
+    }
+    return '(anon)';
+}
+function memberName(node) {
+    if (!node)
+        return null;
+    if (node.type === 'Identifier')
+        return SAFE_IDENTIFIER.test(node.name) ? node.name : null;
+    if (node.type === 'StringLiteral')
+        return SAFE_IDENTIFIER.test(node.value) ? node.value : null;
+    if (node.type === 'MemberExpression' && !node.computed) {
+        const object = memberName(node.object);
+        const property = memberName(node.property);
+        return object && property ? `${object}.${property}` : null;
+    }
+    return null;
+}
+function qualifiedFunctionName(path) {
+    const node = path.node;
+    const localName = functionName(path);
+    const classPath = path.findParent((candidate) => candidate.isClassDeclaration?.() || candidate.isClassExpression?.());
+    if (classPath && (path.isClassMethod?.() || path.isClassPrivateMethod?.())) {
+        const className = classPath.node.id?.name;
+        const method = memberName(node.key);
+        if (className && method)
+            return `${className}.${method}`;
+    }
+    const parent = path.parentPath;
+    if (path.isObjectMethod?.() || parent?.isObjectProperty?.()) {
+        const property = memberName(node.key ?? parent.node.key);
+        const objectExpression = path.isObjectMethod?.() ? parent : parent.parentPath;
+        const declarator = objectExpression?.parentPath;
+        const owner = declarator?.isVariableDeclarator?.()
+            ? memberName(declarator.node.id)
+            : null;
+        if (owner && property)
+            return `${owner}.${property}`;
+    }
+    if (parent?.isVariableDeclarator?.()) {
+        const name = memberName(parent.node.id);
+        if (name)
+            return name;
+    }
+    if (parent?.isAssignmentExpression?.()) {
+        const name = memberName(parent.node.left);
+        if (name)
+            return name;
+    }
+    return localName;
+}
+function enclosingFunctionName(path) {
+    const fn = path.getFunctionParent();
+    return fn ? functionName(fn) : '(top)';
+}
+function sourceFieldsForParameter(fnPath, name) {
+    const binding = fnPath.scope.getBinding(name);
+    if (!binding)
+        return [];
+    const fields = new Set();
+    for (const reference of binding.referencePaths ?? []) {
+        const member = reference.parentPath;
+        const isMember = member?.isMemberExpression() || member?.isOptionalMemberExpression?.();
+        if (!isMember || member.node.object !== reference.node)
+            continue;
+        const property = member.node.property;
+        if (!member.node.computed && property?.name)
+            fields.add(property.name);
+        else if (member.node.computed && typeof property?.value === 'string')
+            fields.add(property.value);
+    }
+    return [...fields].filter(field => /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/.test(field)).sort().slice(0, 48);
+}
+function sourceFieldsForReturnedObject(node) {
+    if (node?.type !== 'ObjectExpression')
+        return [];
+    const fields = new Set();
+    for (const property of node.properties || []) {
+        if (property?.type !== 'ObjectProperty' && property?.type !== 'ObjectMethod')
+            continue;
+        const key = !property.computed && property.key?.name
+            ? property.key.name
+            : typeof property.key?.value === 'string'
+                ? property.key.value
+                : null;
+        if (key && /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/.test(key))
+            fields.add(key);
+    }
+    return [...fields].sort().slice(0, 48);
+}
+function parameterBindings(t, parameter) {
+    if (t.isIdentifier(parameter))
+        return [parameter];
+    if (t.isAssignmentPattern(parameter))
+        return parameterBindings(t, parameter.left);
+    if (t.isRestElement(parameter))
+        return parameterBindings(t, parameter.argument);
+    if (t.isObjectPattern(parameter)) {
+        return parameter.properties.flatMap((property) => t.isRestElement(property)
+            ? parameterBindings(t, property.argument)
+            : t.isObjectProperty(property)
+                ? parameterBindings(t, property.value)
+                : []);
+    }
+    if (t.isArrayPattern(parameter)) {
+        return parameter.elements.flatMap((element) => element ? parameterBindings(t, element) : []);
+    }
+    return [];
+}
+function optionalProbeCall(t, probeName, value) {
+    return t.callExpression(t.identifier(probeName), [value]);
+}
+function capturedSiteProbeDeclaration(t, capturedName, runtimeControlName, passthroughName, runtimeIntegrity, runtimeProbeName, site) {
+    return t.variableDeclaration('const', [t.variableDeclarator(t.identifier(capturedName), t.callExpression(t.functionExpression(null, [], t.blockStatement([
+            t.tryStatement(t.blockStatement([
+                t.variableDeclaration('const', [t.variableDeclarator(t.identifier('selected'), t.callExpression(t.memberExpression(t.identifier(runtimeControlName), t.identifier('safeSelectSiteProbe')), [
+                        t.stringLiteral(runtimeIntegrity),
+                        t.stringLiteral(runtimeProbeName),
+                        t.stringLiteral(site),
+                        t.identifier(passthroughName),
+                    ]))]),
+                t.returnStatement(t.conditionalExpression(t.binaryExpression('===', t.unaryExpression('typeof', t.identifier('selected')), t.stringLiteral('function')), t.identifier('selected'), t.identifier(passthroughName))),
+            ]), t.catchClause(t.identifier('_error'), t.blockStatement([
+                t.returnStatement(t.identifier(passthroughName)),
+            ]))),
+        ])), []))]);
+}
+function runtimeControlDeclarations(t, controlName, helperName, specifier, moduleType, runtimeGuardChannel, runtimeBlockedChannel) {
+    const fallbackModule = (processHostName) => t.objectExpression([t.objectMethod('method', t.identifier('safeSelectProbe'), [], t.blockStatement([t.returnStatement(t.identifier(helperName))])), t.objectMethod('method', t.identifier('safeSelectSiteProbe'), [
+            t.identifier('_integrity'),
+            t.identifier('_name'),
+            t.identifier('_site'),
+            t.identifier('passthrough'),
+        ], t.blockStatement(processHostName ? [
+            t.variableDeclaration('let', [t.variableDeclarator(t.identifier('selected'), t.nullLiteral())]),
+            t.returnStatement(t.functionExpression(null, [t.identifier('value')], t.blockStatement([
+                t.ifStatement(t.identifier('selected'), t.returnStatement(t.callExpression(t.identifier('selected'), [t.identifier('value')]))),
+                t.tryStatement(t.blockStatement([
+                    t.ifStatement(t.binaryExpression('in', t.stringLiteral(runtimeBlockedChannel), t.identifier(processHostName)), t.blockStatement([
+                        t.expressionStatement(t.assignmentExpression('=', t.identifier('selected'), t.identifier('passthrough'))),
+                        t.returnStatement(t.identifier('value')),
+                    ])),
+                    t.variableDeclaration('const', [t.variableDeclarator(t.identifier('loaded'), t.memberExpression(t.identifier(processHostName), t.stringLiteral(runtimeGuardChannel), true))]),
+                    t.ifStatement(t.logicalExpression('&&', t.identifier('loaded'), t.binaryExpression('===', t.unaryExpression('typeof', t.memberExpression(t.identifier('loaded'), t.identifier('safeSelectSiteProbe'))), t.stringLiteral('function'))), t.blockStatement([
+                        t.variableDeclaration('const', [t.variableDeclarator(t.identifier('candidate'), t.callExpression(t.memberExpression(t.identifier('loaded'), t.identifier('safeSelectSiteProbe')), [
+                                t.identifier('_integrity'),
+                                t.identifier('_name'),
+                                t.identifier('_site'),
+                                t.identifier('passthrough'),
+                            ]))]),
+                        t.expressionStatement(t.assignmentExpression('=', t.identifier('selected'), t.conditionalExpression(t.binaryExpression('===', t.unaryExpression('typeof', t.identifier('candidate')), t.stringLiteral('function')), t.identifier('candidate'), t.identifier('passthrough')))),
+                        t.returnStatement(t.callExpression(t.identifier('selected'), [t.identifier('value')])),
+                    ])),
+                ]), t.catchClause(t.identifier('_error'), t.blockStatement([
+                    t.expressionStatement(t.assignmentExpression('=', t.identifier('selected'), t.identifier('passthrough'))),
+                ]))),
+                t.returnStatement(t.identifier('value')),
+            ]))),
+        ] : [t.returnStatement(t.identifier('passthrough'))]))]);
+    if (moduleType === 'module') {
+        return [
+            t.importDeclaration([t.importDefaultSpecifier(t.identifier(`${controlName}Imported`))], t.stringLiteral(specifier)),
+            t.variableDeclaration('const', [t.variableDeclarator(t.identifier(controlName), t.conditionalExpression(t.binaryExpression('===', t.unaryExpression('typeof', t.memberExpression(t.identifier(`${controlName}Imported`), t.identifier('safeSelectProbe'))), t.stringLiteral('function')), t.identifier(`${controlName}Imported`), fallbackModule()))]),
+        ];
+    }
+    return [
+        t.variableDeclaration('const', [t.variableDeclarator(t.identifier(controlName), t.callExpression(t.functionExpression(null, [], t.blockStatement([
+                t.tryStatement(t.blockStatement([
+                    t.variableDeclaration('const', [t.variableDeclarator(t.identifier('processHost'), t.callExpression(t.identifier('require'), [t.stringLiteral('node:process')]))]),
+                    t.ifStatement(t.binaryExpression('in', t.stringLiteral(runtimeBlockedChannel), t.identifier('processHost')), t.returnStatement(fallbackModule('processHost'))),
+                    t.variableDeclaration('const', [t.variableDeclarator(t.identifier('loaded'), t.memberExpression(t.identifier('processHost'), t.stringLiteral(runtimeGuardChannel), true))]),
+                    t.returnStatement(t.conditionalExpression(t.logicalExpression('&&', t.identifier('loaded'), t.binaryExpression('===', t.unaryExpression('typeof', t.memberExpression(t.identifier('loaded'), t.identifier('safeSelectProbe'))), t.stringLiteral('function'))), t.identifier('loaded'), fallbackModule('processHost'))),
+                ]), t.catchClause(t.identifier('_error'), t.blockStatement([
+                    t.returnStatement(fallbackModule()),
+                ]))),
+            ])), []))]),
+    ];
+}
+function passthroughHelper(t, helperName) {
+    return t.functionDeclaration(t.identifier(helperName), [t.identifier('_site'), t.identifier('value')], t.blockStatement([t.returnStatement(t.identifier('value'))]));
+}
+function sitePassthroughHelper(t, helperName) {
+    return t.functionDeclaration(t.identifier(helperName), [t.identifier('value')], t.blockStatement([t.returnStatement(t.identifier('value'))]));
+}
+function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, controlChannel, runtimeIntegrity, includedQualifiedNames) {
+    if (hasGeneratedInstrumentation(code))
+        return null;
+    const probes = { branches: 0, parameters: 0, bindings: 0, returns: 0, throws: 0 };
+    const ordinals = new WeakMap();
+    const functionIdentities = new WeakMap();
+    const functionNameCounts = new Map();
+    const selectedOwners = new Map();
+    const sites = new Map();
+    const siteProbeNames = new Map();
+    let helperName = '';
+    let siteHelperName = '';
+    let runtimeControlName = '';
+    let skipFileProbes = false;
+    const nextOrdinal = (path, kind) => {
+        const owner = path.getFunctionParent()?.node ?? path.findParent((candidate) => candidate.isProgram())?.node;
+        if (!owner)
+            return 0;
+        let byKind = ordinals.get(owner);
+        if (!byKind) {
+            byKind = new Map();
+            ordinals.set(owner, byKind);
+        }
+        const next = byKind.get(kind) ?? 0;
+        byKind.set(kind, next + 1);
+        return next;
+    };
+    const ownerIdentity = (path) => {
+        const fn = path.isFunction?.() ? path : path.getFunctionParent();
+        return fn ? functionIdentities.get(fn.node) ?? `${functionName(fn)}:unmapped` : '(top):0';
+    };
+    const site = (fn, qualifiedName, owner, kind, structuralKey, label, allowedFields = []) => {
+        const targetId = `site-${shortHash([sourcePath, owner, kind, structuralKey])}`;
+        const value = `${sourcePath}#${fn}:${targetId}${label ? `(${label})` : ''}`;
+        // Leave room under the ingestion endpoint's 512-character key cap for a
+        // static field label and its longest value-shape outcome.
+        if (value.length > 360)
+            throw new Error(`Telemetry site exceeds the ingestion key limit in ${sourcePath}`);
+        sites.set(value, {
+            probe_key: value,
+            site_id: targetId,
+            source_path: sourcePath,
+            qualified_name: qualifiedName,
+            probe_kind: kind,
+            owner_key: owner,
+            structural_key: structuralKey,
+            ...(label ? { label } : {}),
+            allowed_fields: [...allowedFields],
+        });
+        return value;
+    };
+    const plugin = ({ types: t }) => {
+        const siteProbeName = (path, runtimeProbeName, siteKey) => {
+            const existing = siteProbeNames.get(siteKey);
+            if (existing)
+                return existing;
+            const name = path.scope.getProgramParent().generateUidIdentifier(`__haystackTelemetrySite_${siteProbeNames.size}`).name;
+            siteProbeNames.set(siteKey, name);
+            return name;
+        };
+        const insideAccessor = (path) => {
+            const fn = path.getFunctionParent();
+            return Boolean(fn && (fn.node.kind === 'get' || fn.node.kind === 'set'));
+        };
+        const selectedFunction = (path) => {
+            if (!includedQualifiedNames)
+                return true;
+            const functionPath = path.isFunction?.() ? path : path.getFunctionParent();
+            return Boolean(functionPath && includedQualifiedNames.has(qualifiedFunctionName(functionPath)));
+        };
+        const wrapTest = (path, syntax) => {
+            if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                return;
+            const testPath = path.get('test');
+            const test = testPath?.node;
+            if (!test || !t.isExpression(test))
+                return;
+            const fn = enclosingFunctionName(path);
+            const functionPath = path.getFunctionParent();
+            const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
+            const ordinal = nextOrdinal(path, `branch:${syntax}`);
+            const branchSite = site(fn, qualifiedName, ownerIdentity(path), 'condition', `${syntax}:${ordinal}`);
+            testPath.replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstBranch', branchSite), test));
+            testPath.skip();
+            probes.branches++;
+        };
+        return {
+            visitor: {
+                Program: {
+                    enter(path) {
+                        helperName = path.scope.generateUidIdentifier('__haystackTelemetryPassthrough').name;
+                        siteHelperName = path.scope.generateUidIdentifier('__haystackTelemetrySitePassthrough').name;
+                        runtimeControlName = path.scope.generateUidIdentifier('__haystackTelemetryControl').name;
+                        path.traverse({
+                            CallExpression(candidate) {
+                                if (candidate.get('callee').isIdentifier?.({ name: 'eval' })) {
+                                    skipFileProbes = true;
+                                    candidate.stop();
+                                }
+                            },
+                            WithStatement(candidate) {
+                                skipFileProbes = true;
+                                candidate.stop();
+                            },
+                        });
+                    },
+                    exit(path) {
+                        const optionalProbeCount = probes.branches + probes.bindings + probes.returns + probes.throws;
+                        const totalProbeCount = optionalProbeCount + probes.parameters;
+                        if (skipFileProbes || totalProbeCount === 0)
+                            return;
+                        const declarations = [
+                            ...runtimeControlDeclarations(t, runtimeControlName, helperName, runtimeSpecifier, moduleType, `${controlChannel}_runtimeGuard`, `${controlChannel}_runtimeBlocked`),
+                            passthroughHelper(t, helperName),
+                            sitePassthroughHelper(t, siteHelperName),
+                            ...[...siteProbeNames.entries()].map(([siteKey, name]) => {
+                                const probeKind = sites.get(siteKey)?.probe_kind;
+                                const runtimeProbeName = probeKind === 'condition'
+                                    ? '__hstBranch'
+                                    : probeKind === 'throw'
+                                        ? '__hstThrow'
+                                        : '__hstValue';
+                                return capturedSiteProbeDeclaration(t, name, runtimeControlName, siteHelperName, runtimeIntegrity, runtimeProbeName, siteKey);
+                            }),
+                        ];
+                        const paths = path.unshiftContainer('body', declarations);
+                        for (const inserted of paths)
+                            inserted.skip();
+                    },
+                },
+                Function: {
+                    enter(path) {
+                        const fn = functionName(path);
+                        const occurrence = functionNameCounts.get(fn) ?? 0;
+                        functionNameCounts.set(fn, occurrence + 1);
+                        const owner = `${fn}:${occurrence}`;
+                        functionIdentities.set(path.node, owner);
+                        const qualifiedName = qualifiedFunctionName(path);
+                        if (includedQualifiedNames?.has(qualifiedName)) {
+                            const owners = selectedOwners.get(qualifiedName) ?? new Set();
+                            owners.add(owner);
+                            selectedOwners.set(qualifiedName, owners);
+                        }
+                        if (path.node.kind === 'get' || path.node.kind === 'set')
+                            return;
+                        if (t.isArrowFunctionExpression(path.node) && !t.isBlockStatement(path.node.body)) {
+                            path.ensureBlock();
+                        }
+                    },
+                    exit(path) {
+                        if (skipFileProbes || path.node.kind === 'get' || path.node.kind === 'set' ||
+                            !selectedFunction(path))
+                            return;
+                        const fn = functionName(path);
+                        const statements = [];
+                        for (const [parameterIndex, parameter] of path.node.params.entries()) {
+                            for (const [bindingIndex, identifier] of parameterBindings(t, parameter).entries()) {
+                                const fields = sourceFieldsForParameter(path, identifier.name);
+                                const parameterSite = site(fn, qualifiedFunctionName(path), ownerIdentity(path), 'parameter', `${parameterIndex}:${bindingIndex}:${identifier.name}`, `parameter:${identifier.name}`, fields);
+                                statements.push(t.expressionStatement(optionalProbeCall(t, siteProbeName(path, '__hstValue', parameterSite), t.identifier(identifier.name))));
+                                probes.parameters++;
+                            }
+                        }
+                        if (statements.length > 0 && t.isBlockStatement(path.node.body)) {
+                            const inserted = path.get('body').unshiftContainer('body', statements);
+                            for (const statement of inserted)
+                                statement.skip();
+                        }
+                    },
+                },
+                IfStatement: { exit: (path) => wrapTest(path, 'if') },
+                ConditionalExpression: { exit: (path) => wrapTest(path, 'conditional') },
+                WhileStatement: { exit: (path) => wrapTest(path, 'while') },
+                DoWhileStatement: { exit: (path) => wrapTest(path, 'do-while') },
+                ForStatement: {
+                    exit(path) {
+                        if (path.node.test)
+                            wrapTest(path, 'for');
+                    },
+                },
+                VariableDeclarator: {
+                    exit(path) {
+                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                            return;
+                        if (!t.isIdentifier(path.node.id) || !path.node.init || !t.isExpression(path.node.init))
+                            return;
+                        const fn = enclosingFunctionName(path);
+                        const functionPath = path.getFunctionParent();
+                        const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
+                        const ordinal = nextOrdinal(path, `binding:${path.node.id.name}`);
+                        const valueSite = site(fn, qualifiedName, ownerIdentity(path), 'binding', `${path.node.id.name}:${ordinal}`, `binding:${path.node.id.name}`);
+                        path.get('init').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstValue', valueSite), path.node.init));
+                        path.get('init').skip();
+                        probes.bindings++;
+                    },
+                },
+                ReturnStatement: {
+                    exit(path) {
+                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                            return;
+                        if (!path.node.argument || !t.isExpression(path.node.argument))
+                            return;
+                        const fn = enclosingFunctionName(path);
+                        const functionPath = path.getFunctionParent();
+                        const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
+                        const ordinal = nextOrdinal(path, 'return');
+                        const fields = sourceFieldsForReturnedObject(path.node.argument);
+                        const returnSite = site(fn, qualifiedName, ownerIdentity(path), 'return', String(ordinal), 'return', fields);
+                        path.get('argument').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstValue', returnSite), path.node.argument));
+                        path.get('argument').skip();
+                        probes.returns++;
+                    },
+                },
+                ThrowStatement: {
+                    exit(path) {
+                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                            return;
+                        if (!path.node.argument || !t.isExpression(path.node.argument))
+                            return;
+                        const fn = enclosingFunctionName(path);
+                        const functionPath = path.getFunctionParent();
+                        const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
+                        const ordinal = nextOrdinal(path, 'throw');
+                        const throwSite = site(fn, qualifiedName, ownerIdentity(path), 'throw', String(ordinal), 'throw');
+                        path.get('argument').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstThrow', throwSite), path.node.argument));
+                        path.get('argument').skip();
+                        probes.throws++;
+                    },
+                },
+            },
+        };
+    };
+    const transformed = babel.transformSync(code, {
+        parserOpts: {
+            sourceType: 'unambiguous',
+            plugins: ['jsx'],
+        },
+        plugins: [plugin],
+        babelrc: false,
+        configFile: false,
+        ast: false,
+        code: true,
+        retainLines: true,
+        compact: false,
+    });
+    if (!transformed?.code)
+        throw new Error(`Instrumentation produced no code for ${sourcePath}`);
+    if (!helperName || !siteHelperName || !runtimeControlName) {
+        throw new Error(`Instrumentation produced no helper identity for ${sourcePath}`);
+    }
+    const ambiguousSelections = [...selectedOwners.entries()]
+        .filter(([, owners]) => owners.size > 1)
+        .map(([qualifiedName]) => `${sourcePath}#${qualifiedName}`);
+    if (ambiguousSelections.length > 0) {
+        throw new Error(`Telemetry exact symbol selection is ambiguous: ${ambiguousSelections.join(', ')}; select a symbol with a unique stable identity`);
+    }
+    return {
+        code: prefixAfterShebang(transformed.code, `${INSTRUMENTED_MARKER_COMMENT} `),
+        probes,
+        sites: [...sites.values()].sort((left, right) => left.site_id.localeCompare(right.site_id)),
+    };
+}
+function prefixAfterShebang(code, prefix) {
+    if (!code.startsWith('#!'))
+        return prefix + code;
+    const newline = code.indexOf('\n');
+    if (newline === -1)
+        return `${code}\n${prefix}`;
+    return `${code.slice(0, newline + 1)}${prefix}${code.slice(newline + 1)}`;
+}
+function findNearestPackageType(start, stop) {
+    let current = start;
+    for (;;) {
+        const manifest = join(current, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                return JSON.parse(readFileSync(manifest, 'utf8')).type === 'module' ? 'module' : 'commonjs';
+            }
+            catch (error) {
+                throw new Error(`Could not parse ${manifest}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (current === stop || dirname(current) === current)
+            return 'commonjs';
+        current = dirname(current);
+    }
+}
+function moduleTypeForOutput(output, dist) {
+    const extension = extname(output);
+    if (extension === '.mjs')
+        return 'module';
+    if (extension === '.cjs')
+        return 'commonjs';
+    return findNearestPackageType(dirname(output), process.cwd());
+}
+function runtimeSpecifierForOutput(output, dist) {
+    const runtimeFilename = moduleTypeForOutput(output, dist) === 'module'
+        ? RUNTIME_ESM_FILENAME
+        : RUNTIME_FILENAME;
+    const runtime = normalizedPath(relative(dirname(output), join(dist, RUNTIME_DIRECTORY, runtimeFilename)));
+    return runtime.startsWith('./') || runtime.startsWith('../') ? runtime : `./${runtime}`;
+}
+function bootstrapFor(entry, dist, buildId, runtimeHash, runtimeGuardChannel, runtimeBlockedChannel) {
+    const specifier = runtimeSpecifierForOutput(entry, dist);
+    const moduleType = moduleTypeForOutput(entry, dist);
+    if (moduleType === 'module') {
+        return `/* ${BOOTSTRAP_MARKER} */ import __haystackTelemetryRuntimeV1 from ${JSON.stringify(specifier)};\n__haystackTelemetryRuntimeV1.install({ buildId: ${JSON.stringify(buildId)} });\n`;
+    }
+    // Evaluate a hash-verified runtime outside CommonJS's public cache so a
+    // preload cannot substitute its exports. Generated modules read the captured
+    // capability from process instead of re-requiring a mutable cache entry. A
+    // normal configurable cache entry is still populated for application code,
+    // and applications remain free to delete it.
+    return `/* ${BOOTSTRAP_MARKER} */ (() => { const processHost = require('node:process'); const define = (name, descriptor) => ({}).constructor.defineProperty(processHost, name, descriptor); const block = () => { try { if (!(${JSON.stringify(runtimeBlockedChannel)} in processHost)) define(${JSON.stringify(runtimeBlockedChannel)}, { configurable: false, enumerable: false, writable: false, value: true }); } catch (_ignored) {} }; try { if (${JSON.stringify(runtimeGuardChannel)} in processHost || ${JSON.stringify(runtimeBlockedChannel)} in processHost) { block(); return; } const runtimePath = require.resolve(${JSON.stringify(specifier)}); const source = require('node:fs').readFileSync(runtimePath, 'utf8'); if (require('node:crypto').createHash('sha256').update(source).digest('hex') !== ${JSON.stringify(runtimeHash)}) { block(); return; } const Module = require('node:module'); const loaded = new Module(runtimePath); loaded.filename = runtimePath; loaded.paths = Module._nodeModulePaths(require('node:path').dirname(runtimePath)); loaded._compile(source, runtimePath); loaded.loaded = true; const runtime = loaded.exports; if (!runtime || typeof runtime.install !== 'function' || typeof runtime.safeSelectProbe !== 'function') { block(); return; } define(${JSON.stringify(runtimeGuardChannel)}, { configurable: false, enumerable: false, writable: false, value: runtime }); require.cache[runtimePath] = loaded; runtime.install({ buildId: ${JSON.stringify(buildId)} }); } catch (_error) { block(); } })();\n`;
+}
+function insertEntryBootstrap(code, bootstrap) {
+    const bootstrapAst = babel.parseSync(bootstrap, {
+        sourceType: 'unambiguous',
+    });
+    if (!bootstrapAst?.program?.body?.length) {
+        throw new Error('Telemetry bootstrap produced no statements');
+    }
+    const transformed = babel.transformSync(code, {
+        parserOpts: {
+            sourceType: 'unambiguous',
+            plugins: ['jsx'],
+        },
+        plugins: [() => ({
+                visitor: {
+                    Program: {
+                        exit(path) {
+                            path.unshiftContainer('body', bootstrapAst.program.body);
+                        },
+                    },
+                },
+            })],
+        babelrc: false,
+        configFile: false,
+        ast: false,
+        code: true,
+        retainLines: true,
+        compact: false,
+    });
+    if (!transformed?.code)
+        throw new Error('Telemetry bootstrap produced no entry output');
+    return transformed.code;
+}
+function esmRuntimeWrapper(runtimeHash) {
+    return `import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import Module from 'node:module';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const fallback = Object.freeze({
+  install() { return { enabled: false, reason: 'runtime-unavailable' }; },
+  safeSelectProbe(_integrity, _name, passthrough) { return passthrough; },
+  safeSelectSiteProbe(_integrity, _name, _site, passthrough) { return passthrough; },
+});
+
+const runtime = (() => {
+  try {
+    const filename = fileURLToPath(new URL('./${RUNTIME_FILENAME}', import.meta.url));
+    const source = readFileSync(filename, 'utf8');
+    if (createHash('sha256').update(source).digest('hex') !== ${JSON.stringify(runtimeHash)}) return fallback;
+    const loaded = new Module(filename);
+    loaded.filename = filename;
+    loaded.paths = Module._nodeModulePaths(dirname(filename));
+    loaded._compile(source, filename);
+    return loaded.exports && typeof loaded.exports.safeSelectProbe === 'function'
+      ? loaded.exports
+      : fallback;
+  } catch (_error) {
+    return fallback;
+  }
+})();
+
+export default runtime;
+`;
+}
+function sourceForOutput(output, dist, sourceRoot) {
+    const rel = relative(dist, output);
+    const stem = rel.slice(0, -extname(rel).length);
+    const matches = SOURCE_EXTENSIONS
+        .map(extension => join(sourceRoot, `${stem}${extension}`))
+        .filter(candidate => existsSync(candidate) && statSync(candidate).isFile());
+    if (matches.length > 1) {
+        throw new Error(`Output ${normalizedPath(rel)} maps to multiple source files: ${matches.map(normalizedPath).join(', ')}`);
+    }
+    return matches[0] ?? null;
+}
+function runtimeAssetPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'telemetry', RUNTIME_FILENAME);
+}
+function readExistingManifest(path) {
+    if (!existsSync(path))
+        return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed.schema_version !== MANIFEST_SCHEMA_VERSION || !Array.isArray(parsed.sites)) {
+        throw new Error(`Telemetry instrumentation manifest at ${path} is outdated; rebuild the output directory`);
+    }
+    return { ...parsed, already_instrumented: true };
+}
+export function instrumentNodeTelemetryBuild(distDirectory, options) {
+    const requestedDist = resolve(distDirectory);
+    if (!existsSync(requestedDist) || !statSync(requestedDist).isDirectory()) {
+        throw new Error(`Compiled output directory not found: ${requestedDist}`);
+    }
+    const dist = realpathSync(requestedDist);
+    const entry = resolve(dist, options.entry);
+    assertInside(dist, entry, 'Entry');
+    if (!existsSync(entry) || !statSync(entry).isFile())
+        throw new Error(`Entry file not found: ${entry}`);
+    const requestedSourceRoot = resolve(options.sourceRoot ?? join(dirname(dist), 'src'));
+    if (!existsSync(requestedSourceRoot) || !statSync(requestedSourceRoot).isDirectory()) {
+        throw new Error(`Source directory not found: ${requestedSourceRoot}`);
+    }
+    const sourceRoot = realpathSync(requestedSourceRoot);
+    const selectedSymbolsBySource = new Map();
+    for (const selected of options.includeSymbols ?? []) {
+        if (!selected || typeof selected.sourcePath !== 'string' ||
+            typeof selected.qualifiedName !== 'string' ||
+            !SAFE_SOURCE_PATH.test(selected.sourcePath) ||
+            selected.sourcePath.startsWith('/') || selected.sourcePath.includes('\\') ||
+            selected.sourcePath.split('/').some(part => !part || part === '.' || part === '..') ||
+            !selected.qualifiedName || selected.qualifiedName.length > 256) {
+            throw new Error('Telemetry includeSymbols entries require safe exact sourcePath and qualifiedName values');
+        }
+        const names = selectedSymbolsBySource.get(selected.sourcePath) ?? new Set();
+        names.add(selected.qualifiedName);
+        selectedSymbolsBySource.set(selected.sourcePath, names);
+    }
+    const selectiveInstrumentation = options.includeSymbols !== undefined;
+    const runtimeDirectory = join(dist, RUNTIME_DIRECTORY);
+    const manifestPath = join(runtimeDirectory, MANIFEST_FILENAME);
+    const existing = readExistingManifest(manifestPath);
+    if (existing) {
+        const requestedEntry = normalizedPath(relative(dist, entry));
+        if (existing.entry !== requestedEntry) {
+            throw new Error(`Output is already instrumented for entry ${existing.entry}, not ${requestedEntry}; rebuild before changing entry`);
+        }
+        if (!existsSync(join(dist, existing.runtime))) {
+            throw new Error('Telemetry instrumentation manifest exists but its runtime is missing; rebuild the output directory');
+        }
+        for (const file of existing.instrumented_files) {
+            const output = join(dist, file.output_path);
+            const valid = existsSync(output) && (file.output_path === existing.entry
+                ? hasGeneratedEntryBootstrap(readFileSync(output, 'utf8'))
+                : generatedBody(readFileSync(output, 'utf8')).startsWith(INSTRUMENTED_MARKER_COMMENT));
+            if (!valid) {
+                throw new Error(`Telemetry instrumentation manifest is stale for ${file.output_path}; rebuild the output directory`);
+            }
+        }
+        return existing;
+    }
+    const bundledRuntime = normalizeLineEndings(readFileSync(runtimeAssetPath(), 'utf8'));
+    const outputFiles = fg.sync('**/*.{js,cjs,mjs}', {
+        cwd: dist,
+        onlyFiles: true,
+        dot: true,
+        ignore: [`${RUNTIME_DIRECTORY}/**`, '**/node_modules/**'],
+    }).map(file => resolve(dist, file))
+        .filter(file => normalizeLineEndings(readFileSync(file, 'utf8')) !== bundledRuntime)
+        .sort();
+    if (outputFiles.length === 0)
+        throw new Error(`No JavaScript output files found under ${dist}`);
+    if (outputFiles.some(file => hasGeneratedInstrumentation(readFileSync(file, 'utf8')))) {
+        throw new Error('Found instrumented files without a matching manifest; rebuild the output directory before retrying');
+    }
+    const controlChannel = `__haystackTelemetryControl_${shortHash(outputFiles.flatMap(output => [
+        normalizedPath(relative(dist, output)),
+        normalizeLineEndings(readFileSync(output, 'utf8')),
+    ]))}`;
+    const runtimeTemplate = readFileSync(runtimeAssetPath(), 'utf8');
+    if (!runtimeTemplate.includes(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER) ||
+        !runtimeTemplate.includes(RUNTIME_INTEGRITY_PLACEHOLDER)) {
+        throw new Error('Telemetry runtime is missing its authentication placeholders');
+    }
+    const runtimeChannelSource = runtimeTemplate.replaceAll(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER, controlChannel);
+    const runtimeIntegrity = createHash('sha256').update(runtimeChannelSource).digest('hex');
+    const authenticatedRuntime = runtimeChannelSource.replaceAll(RUNTIME_INTEGRITY_PLACEHOLDER, runtimeIntegrity);
+    const authenticatedRuntimeHash = createHash('sha256').update(authenticatedRuntime).digest('hex');
+    const pending = [];
+    const skipped = [];
+    for (const output of outputFiles) {
+        const source = sourceForOutput(output, dist, sourceRoot);
+        if (!source) {
+            skipped.push(normalizedPath(relative(dist, output)));
+            continue;
+        }
+        const sourcePath = normalizedPath(relative(process.cwd(), source));
+        if (sourcePath === '..' || sourcePath.startsWith('../') || isAbsolute(sourcePath)) {
+            throw new Error(`Source file is outside the current project directory: ${sourcePath}`);
+        }
+        if (!SAFE_SOURCE_PATH.test(sourcePath)) {
+            throw new Error(`Source path contains a telemetry-reserved character (# or |): ${sourcePath}`);
+        }
+        const transformed = instrumentSource(readFileSync(output, 'utf8'), sourcePath, runtimeSpecifierForOutput(output, dist), moduleTypeForOutput(output, dist), controlChannel, runtimeIntegrity, selectiveInstrumentation ? selectedSymbolsBySource.get(sourcePath) ?? new Set() : null);
+        if (transformed)
+            pending.push({ output, source: sourcePath, ...transformed });
+    }
+    if (pending.length === 0) {
+        throw new Error('No compiled files had an exact source-file match; pass --source-root with the correct source directory');
+    }
+    if (!pending.some(file => file.output === entry)) {
+        throw new Error('The entry file did not map to an exact source file; pass --source-root with the correct source directory');
+    }
+    const instrumentedSites = pending.flatMap(file => file.sites)
+        .sort((left, right) => left.site_id.localeCompare(right.site_id));
+    if (selectiveInstrumentation) {
+        const matched = new Set(instrumentedSites.map(site => `${site.source_path}\0${site.qualified_name}`));
+        const unmatched = (options.includeSymbols ?? []).filter(selected => !matched.has(`${selected.sourcePath}\0${selected.qualifiedName}`));
+        if (unmatched.length > 0) {
+            throw new Error(`Telemetry exact symbol selection did not match: ${unmatched.map(selected => `${selected.sourcePath}#${selected.qualifiedName}`).join(', ')}`);
+        }
+    }
+    if (instrumentedSites.length > MAX_INSTRUMENTED_SITES) {
+        throw new Error(`Build contains ${instrumentedSites.length} telemetry sites; maximum is ${MAX_INSTRUMENTED_SITES}`);
+    }
+    const buildId = shortHash(pending.flatMap(file => [
+        normalizedPath(relative(dist, file.output)),
+        file.code,
+    ]));
+    const runtimeGuardChannel = `${controlChannel}_runtimeGuard`;
+    const runtimeBlockedChannel = `${controlChannel}_runtimeBlocked`;
+    const bootstrap = bootstrapFor(entry, dist, buildId, authenticatedRuntimeHash, runtimeGuardChannel, runtimeBlockedChannel);
+    for (const file of pending) {
+        writeFileSync(file.output, file.output === entry ? insertEntryBootstrap(file.code, bootstrap) : file.code);
+    }
+    mkdirSync(runtimeDirectory, { recursive: true });
+    writeFileSync(join(runtimeDirectory, RUNTIME_FILENAME), authenticatedRuntime);
+    writeFileSync(join(runtimeDirectory, RUNTIME_ESM_FILENAME), esmRuntimeWrapper(authenticatedRuntimeHash));
+    const result = {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        build_id: buildId,
+        dist_directory: dist,
+        entry: normalizedPath(relative(dist, entry)),
+        runtime: `${RUNTIME_DIRECTORY}/${RUNTIME_FILENAME}`,
+        instrumented_files: pending.map(file => ({
+            output_path: normalizedPath(relative(dist, file.output)),
+            source_path: file.source,
+            probes: file.probes,
+        })),
+        sites: instrumentedSites,
+        skipped_unmapped_files: skipped,
+        already_instrumented: false,
+    };
+    writeFileSync(manifestPath, `${JSON.stringify(result, null, 2)}\n`);
+    return result;
+}
+export async function telemetryInstrumentCommand(distDirectory, options) {
+    let includeSymbols = options.includeSymbols;
+    if (options.includeSymbolsFile) {
+        const parsed = JSON.parse(readFileSync(resolve(options.includeSymbolsFile), 'utf8'));
+        const rows = Array.isArray(parsed) ? parsed : parsed?.symbols;
+        if (!Array.isArray(rows)) {
+            throw new Error('--include-symbols JSON must be an array or an object with a symbols array');
+        }
+        includeSymbols = rows;
+    }
+    const result = instrumentNodeTelemetryBuild(distDirectory, { ...options, includeSymbols });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.already_instrumented) {
+        console.log(chalk.dim(`Telemetry already instrumented (build ${result.build_id}).`));
+        return;
+    }
+    const probes = result.instrumented_files.reduce((total, file) => total + file.probes.branches + file.probes.parameters + file.probes.bindings + file.probes.returns + file.probes.throws, 0);
+    console.log(chalk.green(`Instrumented ${result.instrumented_files.length} file(s) with ${probes} telemetry probes.`));
+    console.log(chalk.dim('No source imports were added. Set HAYSTACK_TELEMETRY=1, HAYSTACK_TELEMETRY_ENDPOINT, and HAYSTACK_TELEMETRY_TOKEN at runtime.'));
+    if (result.skipped_unmapped_files.length > 0) {
+        console.log(chalk.yellow(`Skipped ${result.skipped_unmapped_files.length} generated/unmapped file(s); see --json for exact paths.`));
+    }
+}