@haystackeditor/cli 0.24.1 → 0.25.0

package/dist/commands/telemetry.js

@@ -1,10 +1,13 @@
-import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, 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';
+import { SERVER_FIELDS_PER_SITE, SETTINGS_FILE_PATH, SETTINGS_PROPOSAL_PATH, serverRuntimeContract, settingLiteralProblem, settingRefusal, } from './server-telemetry-contract.js';
+import { buildTypeIndex, declaredFields, literalDomain, memberType, } from '../telemetry/typed-source.js';
 // @babel/core intentionally has no bundled declarations. Keep this small
 // build-transform boundary dynamic instead of leaking `any` into CLI contracts.
 // It is loaded on first use, not at module top: loading it costs tens of
@@ -31,11 +34,15 @@ 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 RUNTIME_CONTRACT_PLACEHOLDER = '/* __HAYSTACK_SERVER_CONTRACT__ */ null';
+// v4: sampler 5's sites (declared fields from typed source, approved setting literals).
+const MANIFEST_SCHEMA_VERSION = 'haystack-node-telemetry-instrumentation-v4';
 const MAX_INSTRUMENTED_SITES = 50_000;
 const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs'];
+const TYPED_SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
 const SAFE_SOURCE_PATH = /^[^#|\r\n]+$/;
 const SAFE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;
+const factsKey = (qualifiedName, label) => `${qualifiedName}\0${label}`;
 function generatedBody(code) {
     const body = code.startsWith('#!')
         ? code.slice(code.indexOf('\n') + 1)
@@ -137,8 +144,9 @@ function enclosingFunctionName(path) {
     const fn = path.getFunctionParent();
     return fn ? functionName(fn) : '(top)';
 }
-function sourceFieldsForParameter(fnPath, name) {
-    const binding = fnPath.scope.getBinding(name);
+/** Field names the code reads on a binding (`value.field`, `value?.['field']`): source-declared, never enumerated. */
+function sourceFieldsForName(scope, name) {
+    const binding = scope.getBinding(name);
     if (!binding)
         return [];
     const fields = new Set();
@@ -153,7 +161,34 @@ function sourceFieldsForParameter(fnPath, 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);
+    return [...fields].filter(field => /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/.test(field)).sort().slice(0, SERVER_FIELDS_PER_SITE);
+}
+/** Rule 9(b): the fields the code reads first (they are what its behaviour depends on), then the fields its type
+ * declares, at most SERVER_FIELDS_PER_SITE. */
+function mergeFields(read, declared) {
+    const fields = [...read];
+    for (const field of declared ?? []) {
+        if (!fields.includes(field) && /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/.test(field))
+            fields.push(field);
+    }
+    return fields.slice(0, SERVER_FIELDS_PER_SITE);
+}
+/** A binding whose initializer is an anonymous function or class takes the binding's name (`const f = () => {}` has
+ * `f.name === 'f'`); wrapping the initializer in a probe call would take that name away, and with it stack frames. */
+function namedByBinding(t, init) {
+    let node = init;
+    while (node && (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node) || t.isTSNonNullExpression(node) ||
+        t.isTSTypeAssertion(node) || t.isParenthesizedExpression(node) || node.type === 'TypeCastExpression')) {
+        node = node.expression;
+    }
+    return t.isArrowFunctionExpression(node) || (t.isFunctionExpression(node) && !node.id) ||
+        (t.isClassExpression(node) && !node.id);
+}
+/** Next route segment config: `export const runtime = 'edge'` makes the module an edge bundle's. */
+function declaresEdgeRuntime(program) {
+    return (program.body ?? []).some((statement) => statement.type === 'ExportNamedDeclaration' && statement.declaration?.type === 'VariableDeclaration' &&
+        statement.declaration.declarations.some((declarator) => declarator.id?.type === 'Identifier' && declarator.id.name === 'runtime' &&
+            declarator.init?.type === 'StringLiteral' && ['edge', 'experimental-edge'].includes(declarator.init.value)));
 }
 function sourceFieldsForReturnedObject(node) {
     if (node?.type !== 'ObjectExpression')
@@ -194,22 +229,43 @@ function parameterBindings(t, parameter) {
 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)),
-            ]))),
-        ])), []))]);
+/**
+ * Rule 13(b), same program: the generated declarations are `var`s and function declarations only, so they are hoisted
+ * with the module. A function of this module that another module calls before this module's body has run (a cyclic
+ * import) reaches its probes before any `const` here would be initialized; a hoisted probe binds the runtime on its first
+ * call instead, and while the runtime cannot be reached yet (an ESM import still in its temporal dead zone) it passes the
+ * value through and tries again on the next call.
+ *
+ *   var control, s0, s1;
+ *   function bind(name, site) { ... resolves control once, then the site's probe ... }
+ *   function site0(value) { return (s0 || (s0 = bind("__hstValue", "<site>")) || sitePass)(value); }
+ */
+function lazySiteProbeDeclarations(t, names, controlExpression, runtimeIntegrity, sites) {
+    const babel = loadBabel();
+    const bind = babel.template.statement(`function ${names.bind}(name, site) {
+    if (${names.control} === undefined) {
+      try { ${names.control} = %%CONTROL%%; } catch (_error) { return null; }
+    }
+    try {
+      const selected = ${names.control}.safeSelectSiteProbe(${JSON.stringify(runtimeIntegrity)}, name, site, ${names.sitePass});
+      return typeof selected === 'function' ? selected : ${names.sitePass};
+    } catch (_error) { return ${names.sitePass}; }
+  }`, { syntacticPlaceholders: true })({ CONTROL: controlExpression });
+    return [
+        t.variableDeclaration('var', [
+            t.variableDeclarator(t.identifier(names.control)),
+            ...sites.map(site => t.variableDeclarator(t.identifier(site.selected))),
+        ]),
+        bind,
+        ...sites.map(site => t.functionDeclaration(t.identifier(site.fn), [t.identifier('value')], t.blockStatement([t.returnStatement(t.callExpression(t.logicalExpression('||', t.logicalExpression('||', t.identifier(site.selected), t.assignmentExpression('=', t.identifier(site.selected), t.callExpression(t.identifier(names.bind), [
+                t.stringLiteral(site.probeName),
+                t.stringLiteral(site.site),
+            ]))), t.identifier(names.sitePass)), [t.identifier('value')]))]))),
+    ];
 }
-function runtimeControlDeclarations(t, controlName, helperName, specifier, moduleType, runtimeGuardChannel, runtimeBlockedChannel) {
+/** Where generated probes find the runtime: the hash-verified ESM import, or the capability the bootstrap put on the
+ * real process object (CommonJS and bundled code), with a pass-through fallback. Evaluated on a probe's first call. */
+function runtimeControl(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'),
@@ -242,29 +298,30 @@ function runtimeControlDeclarations(t, controlName, helperName, specifier, modul
             ]))),
         ] : [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 {
+            imports: [t.importDeclaration([t.importDefaultSpecifier(t.identifier(`${controlName}Imported`))], t.stringLiteral(specifier))],
+            expression: 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'), 
-                        // A bundled module must not name node:process: the bundler
-                        // would resolve it as a module of its own. The global is the
-                        // same object in a Node server.
-                        moduleType === 'bundled'
-                            ? t.memberExpression(t.identifier('globalThis'), t.identifier('process'))
-                            : 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()),
-                ]))),
-            ])), []))]),
-    ];
+    return {
+        imports: [],
+        expression: t.callExpression(t.functionExpression(null, [], t.blockStatement([
+            t.tryStatement(t.blockStatement([
+                t.variableDeclaration('const', [t.variableDeclarator(t.identifier('processHost'), 
+                    // A bundled module must not name node:process: the bundler
+                    // would resolve it as a module of its own. The global is the
+                    // same object in a Node server.
+                    moduleType === 'bundled'
+                        ? t.memberExpression(t.identifier('globalThis'), t.identifier('process'))
+                        : 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'))]));
@@ -272,10 +329,13 @@ function passthroughHelper(t, helperName) {
 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, parserPlugins, recordSourcePositions, skipDirective, moduleScopeProbes, }) {
+/** A selection the caller asked for cannot be honoured: the caller's error, not a file this pass could not transform. */
+class SymbolSelectionError extends Error {
+}
+function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, controlChannel, runtimeIntegrity, includedQualifiedNames, parserPlugins, recordSourcePositions, skipDirective, skipEdgeRuntime, moduleScopeProbes, siteFacts, sourceMap, bootstrap, }) {
     if (hasGeneratedInstrumentation(code))
         return null;
-    let skippedByDirective = false;
+    let skippedModule = false;
     const probes = { branches: 0, parameters: 0, bindings: 0, returns: 0, throws: 0 };
     const ordinals = new WeakMap();
     const functionIdentities = new WeakMap();
@@ -286,6 +346,7 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
     let helperName = '';
     let siteHelperName = '';
     let runtimeControlName = '';
+    let bindName = '';
     let skipFileProbes = false;
     const nextOrdinal = (path, kind) => {
         const owner = path.getFunctionParent()?.node ?? path.findParent((candidate) => candidate.isProgram())?.node;
@@ -308,11 +369,10 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
     // Candidate nodes for the site's source position, most specific first.
     // Nodes this pass synthesizes (the return ensureBlock wraps around an
     // arrow's expression body) have no location; the next candidate does.
-    positionNodes, label, allowedFields = []) => {
+    positionNodes, label, allowedFields = [], settings = null) => {
         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.
+        // Leave room under the ingestion endpoint's 512-character key cap.
         if (value.length > 360)
             throw new Error(`Telemetry site exceeds the ingestion key limit in ${sourcePath}`);
         let position = null;
@@ -332,6 +392,7 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
             structural_key: structuralKey,
             ...(label ? { label } : {}),
             allowed_fields: [...allowedFields],
+            ...(settings && settings.length > 0 ? { settings: [...settings] } : {}),
             ...(position ?? {}),
         });
         return value;
@@ -340,10 +401,12 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
         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;
+                return existing.fn;
+            const program = path.scope.getProgramParent();
+            const fn = program.generateUidIdentifier(`__haystackTelemetrySite_${siteProbeNames.size}`).name;
+            const selected = program.generateUidIdentifier(`__haystackTelemetrySelected_${siteProbeNames.size}`).name;
+            siteProbeNames.set(siteKey, { fn, selected, probeName: runtimeProbeName });
+            return fn;
         };
         const insideAccessor = (path) => {
             const fn = path.getFunctionParent();
@@ -376,14 +439,15 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
             visitor: {
                 Program: {
                     enter(path) {
-                        if (skipDirective && (path.node.directives ?? []).some((directive) => directive.value?.value === skipDirective)) {
-                            skippedByDirective = true;
+                        if ((skipDirective && (path.node.directives ?? []).some((directive) => directive.value?.value === skipDirective)) || (skipEdgeRuntime && declaresEdgeRuntime(path.node))) {
+                            skippedModule = true;
                             path.stop();
                             return;
                         }
                         helperName = path.scope.generateUidIdentifier('__haystackTelemetryPassthrough').name;
                         siteHelperName = path.scope.generateUidIdentifier('__haystackTelemetrySitePassthrough').name;
                         runtimeControlName = path.scope.generateUidIdentifier('__haystackTelemetryControl').name;
+                        bindName = path.scope.generateUidIdentifier('__haystackTelemetryBind').name;
                         path.traverse({
                             CallExpression(candidate) {
                                 if (candidate.get('callee').isIdentifier?.({ name: 'eval' })) {
@@ -400,21 +464,27 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
                     exit(path) {
                         const optionalProbeCount = probes.branches + probes.bindings + probes.returns + probes.throws;
                         const totalProbeCount = optionalProbeCount + probes.parameters;
-                        if (skipFileProbes || totalProbeCount === 0)
+                        // The entry's bootstrap goes first, after the directive prologue (a customer's "use strict" stays first), in
+                        // the same single insertion as the probe declarations: inserted statements are skipped, never instrumented.
+                        const bootstrapStatements = bootstrap
+                            ? loadBabel().parseSync(bootstrap, { sourceType: 'unambiguous' })?.program?.body ?? []
+                            : [];
+                        if (bootstrap && bootstrapStatements.length === 0)
+                            throw new Error('Telemetry bootstrap produced no statements');
+                        if (skipFileProbes || totalProbeCount === 0) {
+                            if (bootstrapStatements.length > 0) {
+                                for (const inserted of path.unshiftContainer('body', bootstrapStatements))
+                                    inserted.skip();
+                            }
                             return;
+                        }
+                        const control = runtimeControl(t, runtimeControlName, helperName, runtimeSpecifier, moduleType, `${controlChannel}_runtimeGuard`, `${controlChannel}_runtimeBlocked`);
                         const declarations = [
-                            ...runtimeControlDeclarations(t, runtimeControlName, helperName, runtimeSpecifier, moduleType, `${controlChannel}_runtimeGuard`, `${controlChannel}_runtimeBlocked`),
+                            ...bootstrapStatements,
+                            ...control.imports,
                             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);
-                            }),
+                            ...lazySiteProbeDeclarations(t, { control: runtimeControlName, bind: bindName, sitePass: siteHelperName }, control.expression, runtimeIntegrity, [...siteProbeNames.entries()].map(([siteKey, names]) => ({ ...names, site: siteKey }))),
                         ];
                         const paths = path.unshiftContainer('body', declarations);
                         for (const inserted of paths)
@@ -445,11 +515,13 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
                             !selectedFunction(path))
                             return;
                         const fn = functionName(path);
+                        const qualifiedName = qualifiedFunctionName(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}`, [identifier, parameter, path.node], `parameter:${identifier.name}`, fields);
+                                const label = `parameter:${identifier.name}`;
+                                const typed = siteFacts?.(qualifiedName, label) ?? null;
+                                const parameterSite = site(fn, qualifiedName, ownerIdentity(path), 'parameter', `${parameterIndex}:${bindingIndex}:${identifier.name}`, [identifier, parameter, path.node], label, mergeFields(sourceFieldsForName(path.scope, identifier.name), typed?.fields), typed?.settings ?? null);
                                 statements.push(t.expressionStatement(optionalProbeCall(t, siteProbeName(path, '__hstValue', parameterSite), t.identifier(identifier.name))));
                                 probes.parameters++;
                             }
@@ -477,11 +549,16 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
                             return;
                         if (!t.isIdentifier(path.node.id) || !path.node.init || !t.isExpression(path.node.init))
                             return;
+                        if (namedByBinding(t, path.node.init))
+                            return;
+                        const name = path.node.id.name;
                         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}`, [path.node], `binding:${path.node.id.name}`);
+                        const ordinal = nextOrdinal(path, `binding:${name}`);
+                        const label = `binding:${name}`;
+                        const typed = siteFacts?.(qualifiedName, label) ?? null;
+                        const valueSite = site(fn, qualifiedName, ownerIdentity(path), 'binding', `${name}:${ordinal}`, [path.node], label, mergeFields(sourceFieldsForName(path.scope, name), typed?.fields), typed?.settings ?? null);
                         path.get('init').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstValue', valueSite), path.node.init));
                         path.get('init').skip();
                         probes.bindings++;
@@ -536,8 +613,18 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
         code: true,
         retainLines: true,
         compact: false,
+        // Rule 13(b): the map from the instrumented text back through every earlier transform. An absent input map is
+        // never looked for in the file (the caller decides), so Babel reads nothing on its own.
+        ...(sourceMap
+            ? {
+                filename: sourceMap.filename,
+                sourceFileName: sourceMap.filename,
+                sourceMaps: true,
+                inputSourceMap: sourceMap.input ?? false,
+            }
+            : { sourceMaps: false, inputSourceMap: false }),
     });
-    if (skippedByDirective)
+    if (skippedModule)
         return null;
     if (!transformed?.code)
         throw new Error(`Instrumentation produced no code for ${sourcePath}`);
@@ -548,14 +635,150 @@ function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, cont
         .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`);
+        throw new SymbolSelectionError(`Telemetry exact symbol selection is ambiguous: ${ambiguousSelections.join(', ')}; select a symbol with a unique stable identity`);
     }
+    const marker = `${INSTRUMENTED_MARKER_COMMENT} `;
+    const markerLine = transformed.code.startsWith('#!') ? 1 : 0;
     return {
-        code: prefixAfterShebang(transformed.code, `${INSTRUMENTED_MARKER_COMMENT} `),
+        code: prefixAfterShebang(transformed.code, marker),
+        map: transformed.map ? shiftGeneratedColumns(transformed.map, markerLine, marker.length) : null,
         probes,
         sites: [...sites.values()].sort((left, right) => left.site_id.localeCompare(right.site_id)),
     };
 }
+const BASE64_DIGITS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** The marker comment is prefixed after generation, so the map's first segment on that line moves right by its length
+ * (a line's first generated column is absolute; every later segment on the line is relative to it). */
+function shiftGeneratedColumns(map, line, by) {
+    if (typeof map.mappings !== 'string')
+        return map;
+    const lines = map.mappings.split(';');
+    const target = lines[line];
+    if (!target)
+        return map;
+    let value = 0;
+    let shift = 0;
+    let index = 0;
+    for (; index < target.length; index++) {
+        const digit = BASE64_DIGITS.indexOf(target[index]);
+        if (digit < 0)
+            return map;
+        value += (digit & 31) << shift;
+        shift += 5;
+        if ((digit & 32) === 0)
+            break;
+    }
+    const column = (value & 1 ? -(value >>> 1) : value >>> 1) + by;
+    let encoded = '';
+    let rest = column < 0 ? ((-column) << 1) | 1 : column << 1;
+    do {
+        let digit = rest & 31;
+        rest >>>= 5;
+        if (rest > 0)
+            digit |= 32;
+        encoded += BASE64_DIGITS[digit];
+    } while (rest > 0);
+    lines[line] = encoded + target.slice(index + 1);
+    return { ...map, mappings: lines.join(';') };
+}
+/** One parameter's bindings with the type each is declared with (a destructured binding: its property's type), named
+ * exactly as parameterBindings names the sites. */
+function typedParameterBindings(parameter, annotation, index, resolve) {
+    if (!parameter)
+        return [];
+    if (parameter.type === 'Identifier')
+        return [{ name: parameter.name, annotation: annotation ?? parameter.typeAnnotation, index, resolve }];
+    if (parameter.type === 'AssignmentPattern')
+        return typedParameterBindings(parameter.left, annotation ?? parameter.left?.typeAnnotation, index, resolve);
+    if (parameter.type === 'RestElement')
+        return typedParameterBindings(parameter.argument, null, index, resolve).map(binding => ({ ...binding, annotation: null }));
+    if (parameter.type === 'ObjectPattern') {
+        const own = annotation ?? parameter.typeAnnotation;
+        return parameter.properties.flatMap((property) => {
+            if (property.type === 'RestElement')
+                return typedParameterBindings(property.argument, null, index, resolve).map(binding => ({ ...binding, annotation: null }));
+            if (property.type !== 'ObjectProperty')
+                return [];
+            const key = !property.computed && property.key?.type === 'Identifier' ? property.key.name
+                : property.key?.type === 'StringLiteral' ? property.key.value : null;
+            const member = own && key !== null ? memberType(own, key, index, resolve) : null;
+            return typedParameterBindings(property.value, member?.annotation ?? null, member?.index ?? index, member?.resolve ?? resolve)
+                .map(binding => member ? binding : { ...binding, annotation: null });
+        });
+    }
+    if (parameter.type === 'ArrayPattern') {
+        return parameter.elements.flatMap((element) => typedParameterBindings(element, null, index, resolve))
+            .map((binding) => ({ ...binding, annotation: null }));
+    }
+    return [];
+}
+/** `x as T` and `x satisfies T` declare a binding's type when it has no annotation (never `as const`). */
+function assertedType(init) {
+    let node = init;
+    while (node?.type === 'TSSatisfiesExpression' || node?.type === 'TSAsExpression') {
+        const annotation = node.typeAnnotation;
+        if (!(annotation?.type === 'TSTypeReference' && annotation.typeName?.type === 'Identifier' && annotation.typeName.name === 'const')) {
+            return annotation;
+        }
+        node = node.expression;
+    }
+    return null;
+}
+/**
+ * Rule 9(b)/(c): per site of a TYPED source file (keyed by the site's function and label exactly as instrumentSource
+ * names them), the fields its type declares and its literal domain. Compiled output loses the types, so the compiled-
+ * output path reads the original TypeScript beside it and joins by this key; the bundler path reads the module it
+ * instruments. A key the file declares twice with different facts is ambiguous and keeps neither.
+ */
+export function collectTypedSiteFacts(code, parserPlugins, resolve) {
+    const facts = new Map();
+    const record = (key, annotation, index, resolveImport) => {
+        const domain = annotation ? literalDomain(annotation, index, resolveImport) : null;
+        const value = {
+            fields: annotation ? declaredFields(annotation, index, resolveImport) : [],
+            domain: domain?.literals ?? null,
+            typeNames: domain?.typeNames ?? [],
+        };
+        const existing = facts.get(key);
+        if (existing === undefined)
+            facts.set(key, value);
+        else if ('ambiguous' in existing || JSON.stringify(existing) !== JSON.stringify(value))
+            facts.set(key, { ambiguous: true });
+    };
+    let index = buildTypeIndex(null);
+    loadBabel().transformSync(code, {
+        parserOpts: { sourceType: 'unambiguous', plugins: parserPlugins },
+        plugins: [() => ({
+                visitor: {
+                    Program(path) {
+                        index = buildTypeIndex(path.node);
+                    },
+                    Function(path) {
+                        if (path.node.kind === 'get' || path.node.kind === 'set')
+                            return;
+                        const qualifiedName = qualifiedFunctionName(path);
+                        for (const parameter of path.node.params) {
+                            for (const binding of typedParameterBindings(parameter, null, index, resolve)) {
+                                record(factsKey(qualifiedName, `parameter:${binding.name}`), binding.annotation, binding.index, binding.resolve);
+                            }
+                        }
+                    },
+                    VariableDeclarator(path) {
+                        if (path.node.id?.type !== 'Identifier' || !path.node.init)
+                            return;
+                        const functionPath = path.getFunctionParent();
+                        const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
+                        record(factsKey(qualifiedName, `binding:${path.node.id.name}`), path.node.id.typeAnnotation ?? assertedType(path.node.init), index, resolve);
+                    },
+                },
+            })],
+        babelrc: false,
+        configFile: false,
+        ast: false,
+        code: false,
+    });
+    return facts;
+}
 function prefixAfterShebang(code, prefix) {
     if (!code.startsWith('#!'))
         return prefix + code;
@@ -609,39 +832,6 @@ function bootstrapFor(entry, dist, buildId, runtimeHash, runtimeGuardChannel, ru
     // 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 babel = loadBabel();
-    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';
@@ -699,10 +889,14 @@ function runtimeAssetPath() {
 export function authenticateTelemetryRuntime(controlChannel) {
     const runtimeTemplate = readFileSync(runtimeAssetPath(), 'utf8');
     if (!runtimeTemplate.includes(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER) ||
-        !runtimeTemplate.includes(RUNTIME_INTEGRITY_PLACEHOLDER)) {
+        !runtimeTemplate.includes(RUNTIME_INTEGRITY_PLACEHOLDER) ||
+        !runtimeTemplate.includes(RUNTIME_CONTRACT_PLACEHOLDER)) {
         throw new Error('Telemetry runtime is missing its authentication placeholders');
     }
-    const runtimeChannelSource = runtimeTemplate.replaceAll(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER, controlChannel);
+    // The contract's constants and vocabulary are part of what the integrity covers.
+    const runtimeChannelSource = runtimeTemplate
+        .replaceAll(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER, controlChannel)
+        .replace(RUNTIME_CONTRACT_PLACEHOLDER, JSON.stringify(serverRuntimeContract()));
     const integrity = createHash('sha256').update(runtimeChannelSource).digest('hex');
     const source = runtimeChannelSource.replaceAll(RUNTIME_INTEGRITY_PLACEHOLDER, integrity);
     return { source, integrity, hash: createHash('sha256').update(source).digest('hex') };
@@ -716,6 +910,204 @@ function readExistingManifest(path) {
     }
     return { ...parsed, already_instrumented: true };
 }
+// ─── Typed source and settings (CAPTURE-V1 rule 9b, 9c) ─────────────────────
+/** The repository root settings and repository-relative paths are read against: git's top level, else `start`. */
+export function repositoryRoot(start) {
+    try {
+        return realpathSync(execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: start, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim());
+    }
+    catch {
+        return realpathSync(start);
+    }
+}
+const SETTINGS_LABEL = /^(?:parameter|binding):[A-Za-z_$][A-Za-z0-9_$]{0,63}$/;
+function validSettingsEntry(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const { sourcePath, qualifiedName, label, domain } = entry;
+    return typeof sourcePath === 'string' && SAFE_SOURCE_PATH.test(sourcePath) && !sourcePath.startsWith('/') &&
+        !sourcePath.includes('\\') && sourcePath.split('/').every(part => part && part !== '.' && part !== '..') &&
+        typeof qualifiedName === 'string' && qualifiedName.length >= 1 && qualifiedName.length <= 256 &&
+        typeof label === 'string' && SETTINGS_LABEL.test(label) &&
+        Array.isArray(domain) && domain.length >= 1 && domain.every(literal => settingLiteralProblem(literal) === null);
+}
+const settingsKey = (sourcePath, qualifiedName, label) => `${sourcePath}\0${qualifiedName}\0${label}`;
+/** A settings file (the approved allowlist or a proposal): its valid entries, and what was wrong with the rest. */
+function readSettingsFile(repoRoot, relativePath) {
+    const path = join(repoRoot, relativePath);
+    if (!existsSync(path))
+        return { file: null, entries: [], problems: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        return { file: relativePath, entries: [], problems: [`${relativePath} is not JSON (${error instanceof Error ? error.message : String(error)}); no settings read`] };
+    }
+    const file = parsed;
+    if (file?.version !== 1 || !Array.isArray(file.settings)) {
+        return { file: relativePath, entries: [], problems: [`${relativePath} is not version 1 with a settings list; no settings read`] };
+    }
+    const entries = [];
+    const problems = [];
+    const seen = new Set();
+    file.settings.forEach((entry, index) => {
+        if (!validSettingsEntry(entry)) {
+            problems.push(`${relativePath} settings[${index}] is not a valid entry; skipped`);
+            return;
+        }
+        const key = settingsKey(entry.sourcePath, entry.qualifiedName, entry.label);
+        if (seen.has(key)) {
+            problems.push(`${relativePath} settings[${index}] repeats ${entry.sourcePath}#${entry.qualifiedName} ${entry.label}; the first is used`);
+            return;
+        }
+        seen.add(key);
+        entries.push({ sourcePath: entry.sourcePath, qualifiedName: entry.qualifiedName, label: entry.label, domain: [...entry.domain] });
+    });
+    return { file: relativePath, entries, problems };
+}
+/** Rule 9(c): the repository's reviewed settings allowlist, the only file instrumentation treats as approval (a
+ * proposal never is). A missing file is no settings; an unreadable file or entry is a problem the build reports,
+ * never a reason to fail it. */
+export function readTelemetrySettings(repoRoot) {
+    return readSettingsFile(repoRoot, SETTINGS_FILE_PATH);
+}
+/** Relative imports one hop away, parsed once per build: `./types`, `./types.js` (NodeNext) and `./types/index`. */
+export function typeImportResolver(repoRoot) {
+    const cache = new Map();
+    const parse = (file) => {
+        if (cache.has(file))
+            return cache.get(file);
+        let index = null;
+        try {
+            const plugins = file.endsWith('.tsx') ? BUNDLED_PARSER_PLUGINS['.tsx'] : BUNDLED_PARSER_PLUGINS['.ts'];
+            const ast = loadBabel().parseSync(readFileSync(file, 'utf8'), {
+                parserOpts: { sourceType: 'unambiguous', plugins }, babelrc: false, configFile: false,
+            });
+            index = buildTypeIndex(ast?.program ?? null);
+        }
+        catch {
+            index = null;
+        }
+        cache.set(file, index);
+        return index;
+    };
+    return (fromFile) => (specifier) => {
+        if (!specifier.startsWith('./') && !specifier.startsWith('../'))
+            return null;
+        const base = resolve(dirname(fromFile), specifier);
+        const stem = /\.[cm]?js$/.test(base) ? base.replace(/\.([cm]?)js$/, '') : base;
+        const candidates = [
+            ...['.ts', '.tsx', '.mts', '.cts', '.d.ts'].map(extension => `${stem}${extension}`),
+            ...['index.ts', 'index.tsx', 'index.d.ts'].map(name => join(base, name)),
+        ];
+        const found = candidates.find(candidate => existsSync(candidate) && statSync(candidate).isFile());
+        if (!found)
+            return null;
+        const rel = relative(repoRoot, found);
+        if (rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('node_modules'))
+            return null;
+        return parse(found);
+    };
+}
+/** The typed facts of one source file, or null when it has no types (JavaScript) or Babel cannot read them. */
+function typedFactsOf(absolutePath, code, resolverFor) {
+    const extension = extname(absolutePath);
+    if (!TYPED_SOURCE_EXTENSIONS.has(extension))
+        return null;
+    try {
+        return collectTypedSiteFacts(code, BUNDLED_PARSER_PLUGINS[extension], resolverFor(absolutePath));
+    }
+    catch {
+        return null;
+    }
+}
+const labelName = (label) => label.slice(label.indexOf(':') + 1);
+/** Rule 9(c) at build time: a site records literals only when a person approved them for it AND its typed source still
+ * declares them; refusals and unmatched entries are reported, never fatal. */
+class SettingsApplication {
+    settings;
+    approved = new Map();
+    matched = new Set();
+    applied = new Map();
+    refused = new Map();
+    constructor(settings) {
+        this.settings = settings;
+        for (const entry of settings.entries)
+            this.approved.set(settingsKey(entry.sourcePath, entry.qualifiedName, entry.label), entry);
+    }
+    lookup(repoSourcePath, facts) {
+        return (qualifiedName, label) => {
+            const typed = facts?.get(factsKey(qualifiedName, label));
+            const usable = typed && !('ambiguous' in typed) ? typed : null;
+            const key = settingsKey(repoSourcePath, qualifiedName, label);
+            const entry = this.approved.get(key);
+            let settings = null;
+            if (entry) {
+                this.matched.add(key);
+                const where = { source_path: repoSourcePath, qualified_name: qualifiedName, label };
+                if (!usable?.domain) {
+                    this.refused.set(key, { ...where, why: 'its typed source no longer declares a literal domain here' });
+                }
+                else {
+                    const literals = entry.domain.filter(literal => usable.domain.some(declared => Object.is(declared, literal)));
+                    const why = settingRefusal([labelName(label), ...usable.typeNames], literals);
+                    if (why)
+                        this.refused.set(key, { ...where, why });
+                    else {
+                        settings = literals;
+                        this.applied.set(key, { ...where, literals });
+                    }
+                }
+            }
+            return usable || settings ? { fields: usable?.fields ?? [], settings } : null;
+        };
+    }
+    report(extra) {
+        for (const row of extra?.applied ?? [])
+            this.applied.set(settingsKey(row.source_path, row.qualified_name, row.label), row);
+        for (const row of extra?.refused ?? [])
+            this.refused.set(settingsKey(row.source_path, row.qualified_name, row.label), row);
+        for (const key of extra?.matched ?? [])
+            this.matched.add(key);
+        return {
+            file: this.settings.file,
+            problems: [...this.settings.problems],
+            applied: [...this.applied.values()],
+            refused: [...this.refused.values()],
+            unmatched: [...this.approved].filter(([key]) => !this.matched.has(key)).map(([, entry]) => entry),
+        };
+    }
+    matchedKeys() {
+        return [...this.matched];
+    }
+}
+// ─── Source maps (rule 13b) ──────────────────────────────────────────────────
+const SOURCE_MAPPING_COMMENT = /(?:^|\n)[ \t]*\/\/[#@][ \t]+sourceMappingURL=([^\s'"`]+)[ \t]*\s*$/;
+/** The compiled file's own source map (its trailing sourceMappingURL: a data URL or a file beside it), read before the
+ * transform so the instrumented file's map composes through it. `comment: null` when the file names no map; `map: null`
+ * when it names one that cannot be read (the file then keeps its comment and its lines, columns uncomposed). */
+function compiledSourceMap(output, code) {
+    const found = SOURCE_MAPPING_COMMENT.exec(code);
+    if (!found)
+        return { comment: null, url: null, map: null, path: null };
+    const url = found[1];
+    try {
+        const inline = /^data:application\/json;(?:charset[:=][^;,]+;)?base64,(.+)$/.exec(url);
+        if (inline)
+            return { comment: found[0], url, map: JSON.parse(Buffer.from(inline[1], 'base64').toString('utf8')), path: null };
+        if (/^[a-z][a-z0-9+.-]*:/i.test(url))
+            return { comment: found[0], url, map: null, path: null };
+        const path = resolve(dirname(output), decodeURIComponent(url));
+        return { comment: found[0], url, map: JSON.parse(readFileSync(path, 'utf8')), path };
+    }
+    catch {
+        return { comment: found[0], url, map: null, path: null };
+    }
+}
+// ─── Compiled-output instrumentation ────────────────────────────────────────
 export function instrumentNodeTelemetryBuild(distDirectory, options) {
     const requestedDist = resolve(distDirectory);
     if (!existsSync(requestedDist) || !statSync(requestedDist).isDirectory()) {
@@ -787,8 +1179,66 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
         normalizeLineEndings(readFileSync(output, 'utf8')),
     ]))}`;
     const { source: authenticatedRuntime, integrity: runtimeIntegrity, hash: authenticatedRuntimeHash, } = authenticateTelemetryRuntime(controlChannel);
+    const repoRoot = repositoryRoot(process.cwd());
+    const settings = new SettingsApplication(readTelemetrySettings(repoRoot));
+    const resolverFor = typeImportResolver(repoRoot);
     const pending = [];
     const skipped = [];
+    const untransformed = [];
+    /** One compiled file's rewrite, computed in memory; null when the file stays as built (named in `untransformed`). */
+    const transformCompiled = (output, source, sourcePath, bootstrap) => {
+        const outputPath = normalizedPath(relative(dist, output));
+        try {
+            // Rule 9(b)/(c): the compiled file has lost its types; the TypeScript it came from has them, joined to the
+            // compiled sites by function and label (sites whose names compilation changed stay shape-only).
+            const typed = typedFactsOf(source, readFileSync(source, 'utf8'), resolverFor);
+            let code = readFileSync(output, 'utf8');
+            const ownMap = compiledSourceMap(output, code);
+            if (ownMap.comment !== null && ownMap.map === null) {
+                // Rule 13(b): a map that cannot be composed would leave the customer's stack traces pointing at the wrong
+                // columns, so the file is left exactly as built.
+                untransformed.push({ output_path: outputPath, reason: `its source map (${ownMap.url}) could not be read to compose` });
+                return null;
+            }
+            // A readable map is consumed and re-emitted composed; its comment is removed first so the output names one map.
+            if (ownMap.comment !== null)
+                code = code.slice(0, code.length - ownMap.comment.length);
+            const transformed = instrumentSource(code, {
+                sourcePath,
+                runtimeSpecifier: runtimeSpecifierForOutput(output, dist),
+                moduleType: moduleTypeForOutput(output, dist),
+                controlChannel,
+                runtimeIntegrity,
+                includedQualifiedNames: selectiveInstrumentation ? selectedSymbolsBySource.get(sourcePath) ?? new Set() : null,
+                parserPlugins: ['jsx'],
+                // Compiled output's coordinates are not the source's, so sites carry none (see InstrumentedSite.line).
+                recordSourcePositions: false,
+                moduleScopeProbes: true,
+                siteFacts: settings.lookup(normalizedPath(relative(repoRoot, source)), typed),
+                sourceMap: ownMap.map !== null ? { filename: output, input: ownMap.map } : null,
+                bootstrap,
+            });
+            if (!transformed)
+                return null;
+            return {
+                output,
+                source: sourcePath,
+                code: transformed.code,
+                map: ownMap.map !== null && transformed.map ? { path: ownMap.path, url: ownMap.url, json: transformed.map } : null,
+                probes: transformed.probes,
+                sites: transformed.sites,
+                typed: typed !== null,
+            };
+        }
+        catch (error) {
+            if (error instanceof SymbolSelectionError)
+                throw error;
+            // Rule 13(b): a file this pass cannot transform ships exactly as the build wrote it, named in the report.
+            untransformed.push({ output_path: outputPath, reason: transformFailure(error) });
+            return null;
+        }
+    };
+    const sources = new Map();
     for (const output of outputFiles) {
         const source = sourceForOutput(output, dist, sourceRoot);
         if (!source) {
@@ -802,27 +1252,16 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
         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,
-            runtimeSpecifier: runtimeSpecifierForOutput(output, dist),
-            moduleType: moduleTypeForOutput(output, dist),
-            controlChannel,
-            runtimeIntegrity,
-            includedQualifiedNames: selectiveInstrumentation ? selectedSymbolsBySource.get(sourcePath) ?? new Set() : null,
-            parserPlugins: ['jsx'],
-            // Compiled output has no source map here: its coordinates are not the
-            // source's, so sites carry none (see InstrumentedSite.line).
-            recordSourcePositions: false,
-            moduleScopeProbes: true,
-        });
-        if (transformed)
-            pending.push({ output, source: sourcePath, ...transformed });
+        sources.set(output, { source, sourcePath });
+        const file = transformCompiled(output, source, sourcePath);
+        if (file)
+            pending.push(file);
     }
     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');
+        throw new Error('The entry file did not map to an exact source file, or could not be transformed; 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));
@@ -843,12 +1282,35 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
     const runtimeGuardChannel = `${controlChannel}_runtimeGuard`;
     const runtimeBlockedChannel = `${controlChannel}_runtimeBlocked`;
     const bootstrap = bootstrapFor(entry, dist, buildId, authenticatedRuntimeHash, runtimeGuardChannel, runtimeBlockedChannel);
+    // The entry is transformed again from its built text with the bootstrap inside the same transform, so its map is
+    // generated after the bootstrap moved its lines and columns (the build identity hashes the bootstrap-free text).
+    const entryIndex = pending.findIndex(file => file.output === entry);
+    const entrySource = sources.get(entry);
+    const bootstrapped = transformCompiled(entry, entrySource.source, entrySource.sourcePath, bootstrap);
+    if (!bootstrapped || JSON.stringify(bootstrapped.sites) !== JSON.stringify(pending[entryIndex].sites)) {
+        throw new Error('The entry file could not be given its telemetry bootstrap');
+    }
+    pending[entryIndex] = bootstrapped;
+    // Every artifact is staged before anything replaces the build's own files, then committed by rename: the runtime
+    // first (an ESM file imports it), the manifest last (its presence means the output is instrumented).
+    const staged = [
+        { path: join(runtimeDirectory, RUNTIME_FILENAME), content: authenticatedRuntime },
+        { path: join(runtimeDirectory, RUNTIME_ESM_FILENAME), content: esmRuntimeWrapper(authenticatedRuntimeHash) },
+    ];
     for (const file of pending) {
-        writeFileSync(file.output, file.output === entry ? insertEntryBootstrap(file.code, bootstrap) : file.code);
+        let code = file.code;
+        if (file.map) {
+            const json = JSON.stringify(file.map.json);
+            if (file.map.path === null) {
+                code += `\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${Buffer.from(json).toString('base64')}\n`;
+            }
+            else {
+                code += `\n//# sourceMappingURL=${file.map.url}\n`;
+                staged.push({ path: file.map.path, content: json });
+            }
+        }
+        staged.push({ path: file.output, content: 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,
@@ -859,14 +1321,95 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
             output_path: normalizedPath(relative(dist, file.output)),
             source_path: file.source,
             probes: file.probes,
+            typed: file.typed,
         })),
         sites: instrumentedSites,
         skipped_unmapped_files: skipped,
+        skipped_untransformed_files: untransformed,
+        settings: settings.report(),
         already_instrumented: false,
     };
-    writeFileSync(manifestPath, `${JSON.stringify(result, null, 2)}\n`);
+    staged.push({ path: manifestPath, content: `${JSON.stringify(result, null, 2)}\n` });
+    commitStaged(staged, runtimeDirectory);
     return result;
 }
+/** The build output could not be put back exactly as it was; the files named are left instrumented, without a
+ * manifest, so the runtime installs nothing and every probe passes values through. */
+export class PartialRestoreError extends Error {
+}
+/**
+ * Rule 13(b): replace the build's files all or nothing. Every new content is written to a temporary file beside its
+ * target first; only then is each target moved aside and the new file renamed into place. Any failure renames every
+ * original back (newest first), removes what this created, and rethrows, so the caller can truthfully say the output
+ * is unchanged. Should a restore itself fail, the runtime files stay (an instrumented ESM file imports them) and the
+ * error names the files left instrumented.
+ */
+function commitStaged(writes, runtimeDirectory) {
+    const token = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const createdRuntimeDirectory = !existsSync(runtimeDirectory);
+    mkdirSync(runtimeDirectory, { recursive: true });
+    const steps = [];
+    const discard = () => {
+        for (const step of steps)
+            if (!step.committed)
+                rmSync(step.temporary, { force: true });
+        if (createdRuntimeDirectory)
+            rmSync(runtimeDirectory, { recursive: true, force: true });
+    };
+    try {
+        for (const write of writes) {
+            const temporary = `${write.path}.haystack-stage-${token}`;
+            steps.push({ path: write.path, temporary, backup: null, committed: false });
+            writeFileSync(temporary, write.content);
+        }
+    }
+    catch (error) {
+        discard();
+        throw error;
+    }
+    try {
+        for (const step of steps) {
+            if (existsSync(step.path)) {
+                step.backup = `${step.path}.haystack-original-${token}`;
+                renameSync(step.path, step.backup);
+            }
+            renameSync(step.temporary, step.path);
+            step.committed = true;
+        }
+    }
+    catch (error) {
+        const stranded = [];
+        for (const step of [...steps].reverse()) {
+            try {
+                if (step.backup !== null && existsSync(step.backup))
+                    renameSync(step.backup, step.path);
+                else if (step.committed)
+                    rmSync(step.path, { force: true });
+            }
+            catch {
+                stranded.push(step.path);
+            }
+        }
+        for (const step of steps)
+            rmSync(step.temporary, { force: true });
+        if (stranded.length > 0) {
+            throw new PartialRestoreError(`the build output could not be fully restored after ${error instanceof Error ? error.message : String(error)}; ` +
+                `left instrumented and inactive: ${stranded.join(', ')}`);
+        }
+        if (createdRuntimeDirectory)
+            rmSync(runtimeDirectory, { recursive: true, force: true });
+        throw error;
+    }
+    for (const step of steps)
+        if (step.backup !== null)
+            rmSync(step.backup, { force: true });
+}
+/** A transform failure's one-line reason: Babel's parser message and position, never a code frame (it would copy
+ * customer source into logs). */
+function transformFailure(error) {
+    const first = String(error instanceof Error ? error.message : error).split('\n')[0];
+    return first.replace(/^(?:unknown(?: file)?|\/[^:]*):\s*/, '').slice(0, 300);
+}
 // ─── Bundled (source-level) instrumentation ─────────────────────────────────
 // A bundler packs server code into chunks that mirror no source file, so the
 // compiled-output pass above cannot map them. These two entry points let a
@@ -894,25 +1437,37 @@ const BUNDLED_PARSER_PLUGINS = {
 };
 export const BUNDLED_SOURCE_EXTENSIONS = Object.keys(BUNDLED_PARSER_PLUGINS);
 const BUNDLED_REGISTER_FILENAME = 'register.cjs';
+const bundledSettings = new Map();
+const bundledResolvers = new Map();
 /**
  * Instrument one source module inside a bundler. `sourcePath` is the
  * repository-relative path every site records, so production counts join the
- * change's files and line ranges exactly. A module Babel cannot parse is
- * reported, not thrown: the bundler's compiler may accept syntax Babel does
- * not, and telemetry must never be the reason a build fails. Any other error
- * is ours and stays loud.
+ * change's files and line ranges exactly. Rule 13(b): nothing here fails a
+ * build: a module Babel cannot parse or this pass cannot transform is reported
+ * and ships as written, with its input map.
  */
 export function instrumentBundledModule(code, options) {
-    const parserPlugins = BUNDLED_PARSER_PLUGINS[extname(options.sourcePath)];
-    if (!parserPlugins)
-        throw new Error(`Telemetry cannot parse ${options.sourcePath}: unsupported extension`);
-    if (!SAFE_SOURCE_PATH.test(options.sourcePath) || options.sourcePath.startsWith('/') ||
-        options.sourcePath.split('/').some(part => !part || part === '.' || part === '..')) {
-        throw new Error(`Telemetry source path must be repository-relative without # or |: ${options.sourcePath}`);
-    }
-    let instrumented;
     try {
-        instrumented = instrumentSource(code, {
+        const parserPlugins = BUNDLED_PARSER_PLUGINS[extname(options.sourcePath)];
+        if (!parserPlugins)
+            return { kind: 'unparsed', reason: 'unsupported extension' };
+        if (!SAFE_SOURCE_PATH.test(options.sourcePath) || options.sourcePath.startsWith('/') ||
+            options.sourcePath.split('/').some(part => !part || part === '.' || part === '..')) {
+            return { kind: 'unparsed', reason: 'the source path is not repository-relative or holds # or |' };
+        }
+        let settingsFile = bundledSettings.get(options.sourceRoot);
+        if (!settingsFile) {
+            settingsFile = readTelemetrySettings(options.sourceRoot);
+            bundledSettings.set(options.sourceRoot, settingsFile);
+        }
+        let resolverFor = bundledResolvers.get(options.sourceRoot);
+        if (!resolverFor) {
+            resolverFor = typeImportResolver(options.sourceRoot);
+            bundledResolvers.set(options.sourceRoot, resolverFor);
+        }
+        const settings = new SettingsApplication(settingsFile);
+        const typed = typedFactsOf(options.absolutePath, code, resolverFor);
+        const instrumented = instrumentSource(code, {
             sourcePath: options.sourcePath,
             runtimeSpecifier: '',
             moduleType: 'bundled',
@@ -922,18 +1477,40 @@ export function instrumentBundledModule(code, options) {
             parserPlugins,
             recordSourcePositions: true,
             skipDirective: 'use client',
+            skipEdgeRuntime: true,
             moduleScopeProbes: false,
+            siteFacts: settings.lookup(options.sourcePath, typed),
+            sourceMap: { filename: options.absolutePath, input: options.inputSourceMap },
         });
+        if (!instrumented)
+            return { kind: 'unchanged' };
+        const report = settings.report();
+        return {
+            kind: 'instrumented',
+            ...instrumented,
+            typed: typed !== null,
+            settings: { applied: report.applied, refused: report.refused, matched: settings.matchedKeys() },
+        };
     }
     catch (error) {
-        if (error?.code !== 'BABEL_PARSE_ERROR')
-            throw error;
-        // The parser's own one-line reason and position, e.g. "Missing semicolon.
-        // (1:30)"; the code frame below it would copy customer source into the log.
-        const reason = String(error.message).split('\n')[0].replace(/^unknown:\s*/, '');
-        return { kind: 'unparsed', reason };
+        return { kind: 'unparsed', reason: transformFailure(error) };
     }
-    return instrumented ? { kind: 'instrumented', ...instrumented } : { kind: 'unchanged' };
+}
+export function writeInertTelemetryRuntime(options) {
+    const runtimeDirectory = join(resolve(options.outputDirectory), RUNTIME_DIRECTORY);
+    mkdirSync(runtimeDirectory, { recursive: true });
+    const report = {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        bundler: options.bundler,
+        installed: false,
+        reason: options.reason,
+        skipped_unparsed_files: (options.unparsed ?? []).map(file => ({ source_path: file.sourcePath, reason: file.reason })),
+        sites: [],
+    };
+    writeFileSync(join(runtimeDirectory, MANIFEST_FILENAME), `${JSON.stringify(report, null, 2)}\n`);
+    const registerPath = join(runtimeDirectory, BUNDLED_REGISTER_FILENAME);
+    writeFileSync(registerPath, `/* Haystack telemetry is not installed in this build: ${options.reason.replaceAll('*/', '* /')} */\n`);
+    return { registerPath, report };
 }
 /**
  * Write the runtime, its manifest and the preload that installs it into
@@ -959,6 +1536,12 @@ export function writeBundledTelemetryRuntime(options) {
     if (sites.length > MAX_INSTRUMENTED_SITES) {
         throw new Error(`Build contains ${sites.length} telemetry sites; maximum is ${MAX_INSTRUMENTED_SITES}`);
     }
+    const settings = new SettingsApplication(readTelemetrySettings(options.sourceRoot));
+    const settingsReport = settings.report({
+        applied: modules.flatMap(module => module.settings.applied),
+        refused: modules.flatMap(module => module.settings.refused),
+        matched: modules.flatMap(module => module.settings.matched),
+    });
     // The build identity covers exactly what was instrumented (every site's
     // coordinates), so two builds of identical server source share one identity
     // and any source change produces a new one.
@@ -974,10 +1557,12 @@ export function writeBundledTelemetryRuntime(options) {
         source_root: options.sourceRoot,
         entry: null,
         runtime: `${RUNTIME_DIRECTORY}/${RUNTIME_FILENAME}`,
-        instrumented_files: modules.map(module => ({ source_path: module.sourcePath, probes: module.probes })),
+        instrumented_files: modules.map(module => ({ source_path: module.sourcePath, probes: module.probes, typed: module.typed })),
         skipped_unparsed_files: [...new Map(options.unparsed.map(file => [file.sourcePath, file])).values()]
             .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath))
             .map(file => ({ source_path: file.sourcePath, reason: file.reason })),
+        source_identity: options.sourceIdentity,
+        settings: settingsReport,
         sites,
     };
     writeFileSync(join(runtimeDirectory, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -989,18 +1574,49 @@ export function writeBundledTelemetryRuntime(options) {
     writeFileSync(registerPath, bootstrapFor(registerPath, outputDirectory, buildId, runtime.hash, `${options.controlChannel}_runtimeGuard`, `${options.controlChannel}_runtimeBlocked`));
     return { registerPath, manifest };
 }
+/** The settings and typed-source lines a build prints (rule 8e: init's status repeats them). */
+export function settingsSummary(report, typedFiles, totalFiles) {
+    const lines = [`Haystack telemetry: ${typedFiles} of ${totalFiles} instrumented file(s) read with their types; ` +
+            `${totalFiles - typedFiles} shape-only (no declared fields or setting literals).`];
+    if (report.file === null)
+        lines.push(`Haystack telemetry: no ${SETTINGS_FILE_PATH}; no setting literals are recorded (propose one with \`haystack telemetry settings --propose\`).`);
+    else
+        lines.push(`Haystack telemetry: ${report.applied.length} approved setting(s) recorded as literals; ${report.refused.length} refused; ${report.unmatched.length} approved entr${report.unmatched.length === 1 ? 'y matches' : 'ies match'} no site.`);
+    for (const problem of report.problems)
+        lines.push(`Haystack telemetry: ${problem}`);
+    for (const refused of report.refused)
+        lines.push(`  refused ${refused.source_path}#${refused.qualified_name} ${refused.label}: ${refused.why}`);
+    return lines;
+}
 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');
+    // Rule 13(b): this runs after the customer's build; whatever goes wrong here, the build's output stays as it was
+    // and the command exits 0, saying why telemetry was not added.
+    let result;
+    try {
+        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;
         }
-        includeSymbols = rows;
+        await preloadBabel();
+        result = instrumentNodeTelemetryBuild(distDirectory, { ...options, includeSymbols });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        // Only a failed restore leaves anything changed, and then it says which files (instrumented, inactive).
+        const unchanged = !(error instanceof PartialRestoreError);
+        if (options.json)
+            console.log(JSON.stringify({ instrumented: false, outputUnchanged: unchanged, reason }, null, 2));
+        else
+            console.error(chalk.yellow(unchanged
+                ? `Haystack telemetry was not added; the build output is unchanged: ${reason}`
+                : `Haystack telemetry was not added: ${reason}`));
+        return;
     }
-    await preloadBabel();
-    const result = instrumentNodeTelemetryBuild(distDirectory, { ...options, includeSymbols });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
@@ -1011,8 +1627,174 @@ export async function telemetryInstrumentCommand(distDirectory, options) {
     }
     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.`));
+    for (const line of settingsSummary(result.settings, result.instrumented_files.filter(file => file.typed).length, result.instrumented_files.length))
+        console.log(chalk.dim(line));
     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.`));
     }
+    if (result.skipped_untransformed_files.length > 0) {
+        console.log(chalk.yellow(`Shipped ${result.skipped_untransformed_files.length} file(s) uninstrumented because they could not be transformed:`));
+        for (const file of result.skipped_untransformed_files)
+            console.log(chalk.yellow(`  ${file.output_path}: ${file.reason}`));
+    }
+}
+// ─── `haystack telemetry settings --propose` (rule 9c) ──────────────────────
+const PROPOSE_SKIPPED_PATH = /(?:^|\/)(?:node_modules|__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?tsx?$|\.d\.ts$/;
+function settingsSourceFiles(repoRoot) {
+    let files;
+    try {
+        files = execFileSync('git', ['ls-files', '-z'], {
+            cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 256 * 1024 * 1024,
+        }).split('\0').filter(Boolean);
+    }
+    catch {
+        files = fg.sync('**/*.{ts,tsx,mts,cts}', { cwd: repoRoot, onlyFiles: true, ignore: ['**/node_modules/**'] });
+    }
+    return files
+        .filter(file => TYPED_SOURCE_EXTENSIONS.has(extname(file)) && !PROPOSE_SKIPPED_PATH.test(file) && SAFE_SOURCE_PATH.test(file))
+        .sort();
+}
+/**
+ * Rule 9(c): propose settings. Every parameter and binding of the repository's typed source whose type is a closed set
+ * of literals (a union, a boolean, an enum, an `as const` array or object) is a candidate, refused when its name or a
+ * literal looks like identity or a secret. The proposal (SETTINGS_PROPOSAL_PATH) is the approved entries, unchanged,
+ * plus the new candidates; it approves nothing: only `haystack telemetry settings --approve`, run by a person, makes it
+ * the allowlist instrumentation reads.
+ */
+export function proposeTelemetrySettings(repoRoot) {
+    const existing = readTelemetrySettings(repoRoot);
+    const resolverFor = typeImportResolver(repoRoot);
+    const babel = loadBabel();
+    const known = new Set(existing.entries.map(entry => settingsKey(entry.sourcePath, entry.qualifiedName, entry.label)));
+    const added = [];
+    const refused = [];
+    let typedSource = false;
+    for (const sourcePath of settingsSourceFiles(repoRoot)) {
+        const absolutePath = join(repoRoot, sourcePath);
+        let code;
+        try {
+            code = readFileSync(absolutePath, 'utf8');
+            const program = babel.parseSync(code, {
+                parserOpts: { sourceType: 'unambiguous', plugins: BUNDLED_PARSER_PLUGINS[extname(sourcePath)] },
+                babelrc: false, configFile: false,
+            })?.program;
+            // Client and edge modules are never instrumented, so their parameters are never sites.
+            if (!program || (program.directives ?? []).some((directive) => directive.value?.value === 'use client') ||
+                declaresEdgeRuntime(program))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const facts = typedFactsOf(absolutePath, code, resolverFor);
+        if (!facts)
+            continue;
+        typedSource = true;
+        for (const [key, value] of facts) {
+            const [qualifiedName, label] = key.split('\0');
+            if ('ambiguous' in value || !value.domain)
+                continue;
+            const where = { sourcePath, qualifiedName, label };
+            if (known.has(settingsKey(sourcePath, qualifiedName, label)))
+                continue;
+            const why = settingRefusal([labelName(label), ...value.typeNames], value.domain);
+            if (why) {
+                refused.push({ ...where, why });
+                continue;
+            }
+            added.push({ ...where, domain: value.domain });
+        }
+    }
+    return {
+        path: SETTINGS_PROPOSAL_PATH,
+        approvedPath: SETTINGS_FILE_PATH,
+        file: { version: 1, settings: [...existing.entries, ...added].sort(settingsOrder) },
+        added: added.sort(settingsOrder),
+        refused,
+        typedSource,
+    };
+}
+const settingsOrder = (left, right) => left.sourcePath.localeCompare(right.sourcePath) || left.qualifiedName.localeCompare(right.qualifiedName) ||
+    left.label.localeCompare(right.label);
+/** What promoting the proposal would change in the approved allowlist, entry by entry. */
+export function settingsApprovalDiff(repoRoot) {
+    const approved = readTelemetrySettings(repoRoot);
+    const proposal = readSettingsFile(repoRoot, SETTINGS_PROPOSAL_PATH);
+    const keyOf = (entry) => settingsKey(entry.sourcePath, entry.qualifiedName, entry.label);
+    const before = new Map(approved.entries.map(entry => [keyOf(entry), entry]));
+    const after = new Map(proposal.entries.map(entry => [keyOf(entry), entry]));
+    const refused = proposal.entries.flatMap(entry => {
+        const why = settingRefusal([labelName(entry.label)], entry.domain);
+        return why ? [{ entry, why }] : [];
+    });
+    return {
+        proposal,
+        added: [...after].filter(([key]) => !before.has(key)).map(([, entry]) => entry),
+        removed: [...before].filter(([key]) => !after.has(key)).map(([, entry]) => entry),
+        changed: [...after].flatMap(([key, entry]) => {
+            const from = before.get(key);
+            return from && JSON.stringify(from.domain) !== JSON.stringify(entry.domain) ? [{ from, to: entry }] : [];
+        }),
+        refused,
+    };
+}
+const describeEntry = (entry) => `${entry.sourcePath}#${entry.qualifiedName} ${entry.label}: ${entry.domain.map(literal => JSON.stringify(literal)).join(' | ')}`;
+export async function telemetrySettingsCommand(options) {
+    if (Boolean(options.propose) === Boolean(options.approve)) {
+        throw new Error('Pass --propose (write candidates to review) or --approve (promote the reviewed proposal)');
+    }
+    await preloadBabel();
+    const repoRoot = repositoryRoot(process.cwd());
+    if (options.approve) {
+        const diff = settingsApprovalDiff(repoRoot);
+        if (diff.proposal.file === null)
+            throw new Error(`There is no ${SETTINGS_PROPOSAL_PATH}; run --propose first`);
+        if (diff.proposal.problems.length > 0 || diff.refused.length > 0) {
+            throw new Error(`${SETTINGS_PROPOSAL_PATH} cannot be approved: ${[...diff.proposal.problems,
+                ...diff.refused.map(row => `${describeEntry(row.entry)} (${row.why})`)].join('; ')}`);
+        }
+        if (!options.dryRun) {
+            mkdirSync(join(repoRoot, dirname(SETTINGS_FILE_PATH)), { recursive: true });
+            const approved = { version: 1, settings: [...diff.proposal.entries].sort(settingsOrder) };
+            writeFileSync(join(repoRoot, SETTINGS_FILE_PATH), `${JSON.stringify(approved, null, 2)}\n`);
+            rmSync(join(repoRoot, SETTINGS_PROPOSAL_PATH), { force: true });
+        }
+        if (options.json) {
+            console.log(JSON.stringify({ path: SETTINGS_FILE_PATH, approved: !options.dryRun, added: diff.added, removed: diff.removed,
+                changed: diff.changed }, null, 2));
+            return;
+        }
+        console.log(`${options.dryRun ? 'Approving would change' : 'Approved'} ${SETTINGS_FILE_PATH}: ` +
+            `${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} changed.`);
+        for (const entry of diff.added)
+            console.log(chalk.green(`  + ${describeEntry(entry)}`));
+        for (const entry of diff.removed)
+            console.log(chalk.red(`  - ${describeEntry(entry)}`));
+        for (const row of diff.changed)
+            console.log(chalk.yellow(`  ~ ${describeEntry(row.from)}  ->  ${row.to.domain.map(literal => JSON.stringify(literal)).join(' | ')}`));
+        if (!options.dryRun)
+            console.log('Commit it: telemetry records a value as itself only at an entry in this file.');
+        return;
+    }
+    const proposal = proposeTelemetrySettings(repoRoot);
+    if (!options.dryRun) {
+        mkdirSync(join(repoRoot, dirname(SETTINGS_PROPOSAL_PATH)), { recursive: true });
+        writeFileSync(join(repoRoot, SETTINGS_PROPOSAL_PATH), `${JSON.stringify(proposal.file, null, 2)}\n`);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(proposal, null, 2));
+        return;
+    }
+    if (!proposal.typedSource) {
+        console.log(chalk.yellow('No typed source (TypeScript) was found: server telemetry records shapes and sizes only, no setting literals.'));
+    }
+    console.log(`${options.dryRun ? 'Would propose' : 'Proposed'} ${proposal.added.length} new setting candidate(s) in ${SETTINGS_PROPOSAL_PATH}; ` +
+        `${proposal.refused.length} refused. Nothing is approved yet.`);
+    for (const entry of proposal.added)
+        console.log(chalk.dim(`  ${describeEntry(entry)}`));
+    for (const entry of proposal.refused)
+        console.log(chalk.dim(`  refused ${entry.sourcePath}#${entry.qualifiedName} ${entry.label}: ${entry.why}`));
+    console.log(`Review it (remove any entry or literal that should stay shape-only), then run \`haystack telemetry settings --approve\`,`
+        + ` which shows the change to ${SETTINGS_FILE_PATH} and makes it the allowlist.`);
 }