@hassangameryt/freeflow 0.4.0 → 0.6.0

package/pi-extension/src/output-router/status.ts

@@ -1,791 +0,0 @@
-import { constants as fsConstants } from "node:fs";
-import { access, readFile, stat } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import {
-  DEFAULT_OBSERVED_ROUTING_CONFIG,
-  DEFAULT_OUTPUT_ROUTER_ENABLED,
-  DEFAULT_OUTPUT_ROUTER_PROFILE,
-  DEFAULT_POST_TOOL_ROUTING,
-  DEFAULT_ROUTER_THRESHOLDS,
-  DEFAULT_SCRIPT_TRANSFORM_CONFIG,
-  DEFAULT_STORAGE_POLICY,
-  OBSERVED_ROUTING_PERSISTENCE_MODES,
-  RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES,
-  DEFAULT_VAULT_RETENTION,
-  DEFAULT_VAULT_ROOT,
-  defaultScriptTransformAdaptersHome,
-  createLocalVaultIndex,
-  createVault,
-  discoverEryxPythonSandboxAdaptersFromEnv,
-  discoverJqWasmSandboxAdaptersFromEnv,
-  discoverQuickJsWasiSandboxAdaptersFromEnv,
-  normalizeFreeflowConfig,
-  normalizeLocalFreeflowConfig,
-  probeScriptSandboxAdapters,
-} from "../../../router/dist/index.js";
-import { VALID_MODES, readCapabilityState, readModeState } from "../runtime/runtime-context.js";
-
-const STATUS_ACTIONS = new Set(["status", "doctor", "migration"]);
-const TOP_LEVEL_CONFIG_KEYS = new Set([
-  "enabled",
-  "defaultMode",
-  "interactionContract",
-  "skills",
-  "outputRouter",
-  "observedRouting",
-  "scriptTransform",
-]);
-const OUTPUT_ROUTER_CONFIG_KEYS = new Set([
-  "enabled",
-  "profile",
-  "postToolRouting",
-  "storagePolicy",
-  "largeOutputBytes",
-  "largeOutputLines",
-  "thresholds",
-  "vaultRoot",
-  "vaultRetentionDays",
-  "vault",
-  "generatedPaths",
-  "noisyCommandHints",
-  "hints",
-  "observedRouting",
-  "scriptTransform",
-]);
-const OBSERVED_ROUTING_CONFIG_KEYS = new Set(["enabled", "onRoutingFailure", "mcp", "web", "fetch", "codeSearch"]);
-const OBSERVED_ROUTING_PRODUCER_KEYS = new Set(["enabled", "persistence"]);
-const OBSERVED_ROUTING_MCP_KEYS = new Set(["servers"]);
-const SCRIPT_TRANSFORM_CONFIG_KEYS = new Set([
-  "enabled",
-  "sandbox",
-  "languages",
-  "network",
-  "limits",
-  "rawScriptPersistence",
-]);
-
-export async function buildFreeflowStatusReport(params = {}, ctx) {
-  const action = normalizeStatusAction((params as any).action);
-  const configFile = await readConfigFile(ctx.cwd);
-  const localConfigFile = await readLocalConfigFile(ctx.cwd);
-  const normalized = normalizeFreeflowConfig(configFile.parsed);
-  const localNormalized = normalizeLocalFreeflowConfig(localConfigFile.parsed);
-  const [modeState, runtimeState] = await Promise.all([readModeState(ctx.cwd), readCapabilityState(ctx.cwd)]);
-  const effectiveFreeflowConfig = runtimeState.enabled
-    ? normalized.config
-    : {
-        ...normalized.config,
-        outputRouter: { ...normalized.config.outputRouter, enabled: false },
-        observedRouting: {
-          ...normalized.config.observedRouting,
-          enabled: false,
-        },
-        scriptTransform: {
-          ...normalized.config.scriptTransform,
-          enabled: false,
-        },
-      };
-  const vault = createVault({
-    root: effectiveFreeflowConfig.outputRouter.vault.root,
-    retention: effectiveFreeflowConfig.outputRouter.vault.retention,
-  });
-  const configWarnings = [...normalized.warnings];
-  const localConfigWarnings = [...localNormalized.warnings];
-
-  if (!runtimeState.repositoryConfigured && configFile.exists) {
-    configWarnings.unshift(
-      `.freeflow/config.json is invalid; Freeflow runtime is inactive. ${runtimeState.parseError ?? configFile.parseError ?? "Unknown config error."}`,
-    );
-  }
-  if (
-    isRecord(configFile.parsed) &&
-    configFile.parsed.defaultMode !== undefined &&
-    !VALID_MODES.has(configFile.parsed.defaultMode)
-  ) {
-    configWarnings.push(`Invalid defaultMode=${JSON.stringify(configFile.parsed.defaultMode)}; using workflow.`);
-  }
-  if (runtimeState.localConfigExists && !runtimeState.localConfigValid) {
-    localConfigWarnings.unshift(
-      `.freeflow/local.json is invalid; Freeflow runtime is inactive. ${runtimeState.localConfigParseError ?? localConfigFile.parseError ?? "Unknown local config error."}`,
-    );
-  }
-
-  const scriptSandboxAdapters = [
-    ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
-    ...(await discoverJqWasmSandboxAdaptersFromEnv()),
-    ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
-  ];
-  const [vaultWritability, vaultIndex, scriptSandbox] = await Promise.all([
-    inspectVaultWritability(vault.root),
-    inspectVaultIndex(vault),
-    probeScriptSandboxAdapters({
-      config: effectiveFreeflowConfig.scriptTransform,
-      adapters: scriptSandboxAdapters,
-    }),
-  ]);
-  const migration = migrationReport(configFile.parsed);
-
-  return {
-    toolStatus: "ok",
-    action,
-    generatedAt: new Date().toISOString(),
-    configPath: configFile.path,
-    configExists: configFile.exists,
-    configValid: runtimeState.configValid,
-    repositoryConfigValid: runtimeState.repositoryConfigured,
-    localConfigPath: localConfigFile.path,
-    localConfigExists: localConfigFile.exists,
-    localConfigValid: runtimeState.localConfigValid,
-    configuration: {
-      repository: {
-        path: configFile.path,
-        exists: configFile.exists,
-        valid: runtimeState.repositoryConfigured,
-        error: runtimeState.repositoryConfigured ? null : (runtimeState.parseError ?? configFile.parseError),
-      },
-      personal: {
-        path: localConfigFile.path,
-        exists: localConfigFile.exists,
-        valid: runtimeState.localConfigValid,
-        error: runtimeState.localConfigParseError,
-      },
-      sources: runtimeState.configSources,
-    },
-    mode: {
-      ...modeState,
-      active: modeState.active,
-      resolvedMode: modeState.resolvedMode,
-      defaultModeSource: runtimeState.configSources.defaultMode,
-    },
-    effectiveConfig: {
-      configured: runtimeState.configured,
-      enabled: runtimeState.enabled,
-      defaultMode: runtimeState.defaultMode,
-      sources: runtimeState.configSources,
-      interactionContract: runtimeState.interactionContract,
-      skills: runtimeState.skills,
-      outputRouter: {
-        enabled: effectiveFreeflowConfig.outputRouter.enabled,
-        profile: effectiveFreeflowConfig.outputRouter.profile,
-        postToolRouting: effectiveFreeflowConfig.outputRouter.postToolRouting,
-        storagePolicy: effectiveFreeflowConfig.outputRouter.storagePolicy,
-        thresholds: effectiveFreeflowConfig.outputRouter.thresholds,
-        vault: effectiveFreeflowConfig.outputRouter.vault,
-        hints: effectiveFreeflowConfig.outputRouter.hints ?? {},
-        observedRouting: effectiveFreeflowConfig.observedRouting,
-        scriptTransform: effectiveFreeflowConfig.scriptTransform,
-      },
-    },
-    effectiveLocalConfig: localNormalized.config,
-    effectiveDefaults: {
-      enabled: true,
-      interactionContract: true,
-      skills: { enabled: true },
-      outputRouter: {
-        enabled: DEFAULT_OUTPUT_ROUTER_ENABLED,
-        profile: DEFAULT_OUTPUT_ROUTER_PROFILE,
-        postToolRouting: DEFAULT_POST_TOOL_ROUTING,
-        storagePolicy: DEFAULT_STORAGE_POLICY,
-        thresholds: DEFAULT_ROUTER_THRESHOLDS,
-        vaultRoot: DEFAULT_VAULT_ROOT,
-        vaultRetention: DEFAULT_VAULT_RETENTION,
-        observedRouting: DEFAULT_OBSERVED_ROUTING_CONFIG,
-        scriptTransform: DEFAULT_SCRIPT_TRANSFORM_CONFIG,
-      },
-    },
-    vault: {
-      root: vault.root,
-      configuredRoot: effectiveFreeflowConfig.outputRouter.vault.root,
-      retention: effectiveFreeflowConfig.outputRouter.vault.retention,
-      writability: vaultWritability,
-    },
-    vaultIndex,
-    observedRouting: observedRoutingStatus(effectiveFreeflowConfig.observedRouting),
-    scriptTransform: scriptTransformStatus(effectiveFreeflowConfig.scriptTransform, scriptSandbox),
-    processing: processingStatus(localNormalized.config),
-    recoverabilityDefaults: {
-      freeflowRun:
-        "hybrid-dedupe command capture: exact when exactness-sensitive or duplicate recovery points to a prior exact outputId; small non-sensitive successes may be metadata-only",
-      observedRouting:
-        "exact raw recovery for enabled observed producers when exact persistence is configured; metadata-only stores no raw stream",
-      freeflowTransform:
-        "deterministic transform stores exact transformed-output recovery with source lineage when persisted; script transform is disabled by default and requires an approved sandbox adapter",
-      nativeSafetyNet:
-        "off by default; optional native read/bash safety-net only when outputRouter.postToolRouting is safety-net",
-    },
-    configWarnings,
-    localConfigWarnings,
-    staleConfig: migration.recommendations,
-    migration,
-  };
-}
-
-function normalizeStatusAction(value) {
-  if (typeof value === "string" && STATUS_ACTIONS.has(value)) {
-    return value;
-  }
-  return "status";
-}
-
-async function readConfigFile(cwd) {
-  const path = join(cwd, ".freeflow/config.json");
-  try {
-    const raw = await readFile(path, "utf8");
-    try {
-      const parsed = JSON.parse(raw);
-      return {
-        path,
-        exists: true,
-        raw,
-        parsed: isRecord(parsed) ? parsed : {},
-        parseError: null,
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return { path, exists: true, raw, parsed: {}, parseError: message };
-    }
-  } catch {
-    return { path, exists: false, raw: null, parsed: {}, parseError: null };
-  }
-}
-
-async function readLocalConfigFile(cwd) {
-  const path = join(cwd, ".freeflow/local.json");
-  try {
-    const raw = await readFile(path, "utf8");
-    try {
-      const parsed = JSON.parse(raw);
-      return {
-        path,
-        exists: true,
-        raw,
-        parsed: isRecord(parsed) ? parsed : {},
-        parseError: null,
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return { path, exists: true, raw, parsed: {}, parseError: message };
-    }
-  } catch {
-    return { path, exists: false, raw: null, parsed: {}, parseError: null };
-  }
-}
-
-async function inspectVaultWritability(root) {
-  try {
-    const rootStats = await stat(root);
-    if (!rootStats.isDirectory()) {
-      return {
-        status: "not_directory",
-        detail: "Vault root exists but is not a directory.",
-      };
-    }
-    await access(root, fsConstants.W_OK | fsConstants.X_OK);
-    return { status: "writable", detail: "Vault root exists and is writable." };
-  } catch (error) {
-    const code = error && typeof error === "object" ? (error as any).code : undefined;
-    if (code === "ENOENT") {
-      return inspectMissingVaultRoot(root);
-    }
-    if (code === "EACCES" || code === "EPERM") {
-      return {
-        status: "not_writable",
-        detail: `Vault root exists but is not writable (${code}).`,
-      };
-    }
-    return {
-      status: "unknown",
-      detail: `Could not determine vault writability (${code ?? "unknown"}).`,
-    };
-  }
-}
-
-async function inspectVaultIndex(vault) {
-  try {
-    return await createLocalVaultIndex(vault).status();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      engine: "local-json-sidecar",
-      root: `${vault.root}/index/v1`,
-      available: false,
-      degraded: true,
-      stale: true,
-      rebuildRecommended: true,
-      entryCount: 0,
-      textEntryCount: 0,
-      metadataOnlyEntryCount: 0,
-      outputCount: 0,
-      lastError: message,
-    };
-  }
-}
-
-async function inspectMissingVaultRoot(root) {
-  const ancestor = await nearestExistingAncestor(dirname(root));
-  if (!ancestor) {
-    return {
-      status: "missing_ancestor_unavailable",
-      detail: "Vault root does not exist and no existing writable ancestor could be found. No directory was created.",
-    };
-  }
-
-  if (!ancestor.stats.isDirectory()) {
-    return {
-      status: "missing_ancestor_unavailable",
-      detail: `Nearest existing ancestor is not a directory: ${ancestor.path}. No directory was created.`,
-    };
-  }
-
-  try {
-    await access(ancestor.path, fsConstants.W_OK | fsConstants.X_OK);
-    return {
-      status: "missing_ancestor_writable",
-      detail: `Vault root does not exist; nearest existing ancestor is writable: ${ancestor.path}. Recursive vault creation should be possible. No directory was created.`,
-    };
-  } catch (error) {
-    const code = error && typeof error === "object" ? (error as any).code : undefined;
-    return {
-      status: "missing_ancestor_unavailable",
-      detail: `Vault root does not exist and nearest existing ancestor is not writable: ${ancestor.path} (${code ?? "unknown"}). No directory was created.`,
-    };
-  }
-}
-
-async function nearestExistingAncestor(startPath) {
-  let current = startPath;
-  while (true) {
-    try {
-      return { path: current, stats: await stat(current) };
-    } catch (error) {
-      const code = error && typeof error === "object" ? (error as any).code : undefined;
-      if (code !== "ENOENT") {
-        return null;
-      }
-      const parent = dirname(current);
-      if (parent === current) {
-        return null;
-      }
-      current = parent;
-    }
-  }
-}
-
-function scriptTransformStatus(config, sandboxReport) {
-  const adapterHome = defaultScriptTransformAdaptersHome();
-  return {
-    enabled: config.enabled,
-    sandbox: config.sandbox,
-    adapterAvailable: sandboxReport.adapterAvailable,
-    adapterStatus: sandboxReport.adapterStatus,
-    adapterContractVersion: sandboxReport.contractVersion,
-    configuredLanguages: sandboxReport.configuredLanguages,
-    availableLanguages: sandboxReport.availableLanguages,
-    unavailableLanguages: sandboxReport.unavailableLanguages,
-    registeredAdapters: sandboxReport.registeredAdapters,
-    requiredProofs: sandboxReport.requiredProofs,
-    candidateMechanisms: sandboxReport.candidateMechanisms,
-    network: config.network,
-    limits: config.limits,
-    rawScriptPersistence: config.rawScriptPersistence,
-    executionStatus:
-      config.enabled && sandboxReport.adapterAvailable
-        ? "available"
-        : config.enabled
-          ? "adapter_unavailable"
-          : "disabled",
-    adapterHome,
-    setupCommand:
-      "node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json",
-    notes: [
-      "Script transform is disabled until setup/user config opts in with outputRouter.scriptTransform.enabled=true.",
-      "Setup can install proof-backed adapters into a user-global Freeflow cache and enable only languages that pass sandbox probes.",
-      "No unsandboxed fallback is allowed; script code is not executed without an approved sandbox adapter.",
-      "Raw script text is not persisted by default.",
-      `Global adapter cache: ${adapterHome}. Custom roots may use FREEFLOW_QUICKJS_WASI_ROOT, FREEFLOW_JQ_WASM_ROOT, or FREEFLOW_ERYX_ROOT.`,
-      ...sandboxReport.notes,
-    ],
-  };
-}
-
-function processingStatus(localConfig) {
-  const enabled = localConfig.processing.unsafeUnsandboxed.enabled;
-  return {
-    unsafeUnsandboxed: {
-      enabled,
-      source: ".freeflow/local.json",
-      status: enabled ? "enabled_unsafe" : "disabled",
-      notes: enabled
-        ? [
-            "Unsafe unsandboxed processing is enabled only by local config for this checkout.",
-            "Every unsafe execution result must be labeled unsafe/unsandboxed and must not claim sandbox/read-only/network-off execution.",
-          ]
-        : [
-            "Unsafe unsandboxed processing is disabled. Shared .freeflow/config.json cannot enable it.",
-            "Enable only in local-only .freeflow/local.json after accepting the risk.",
-          ],
-    },
-  };
-}
-
-function observedRoutingStatus(config) {
-  const servers = Object.entries((config.mcp?.servers ?? {}) as Record<string, any>).map(([id, server]) => ({
-    id,
-    enabled: server.enabled,
-    persistence: server.persistence,
-  }));
-
-  return {
-    enabled: config.enabled,
-    onRoutingFailure: config.onRoutingFailure,
-    host: {
-      name: "pi",
-      outputReplacement: "available",
-      reason:
-        "Pi tool_result hooks can modify tool results; observed routing remains controlled by explicit producer/server config.",
-    },
-    mcp: {
-      configuredServerCount: servers.length,
-      servers,
-    },
-    web: config.web,
-    fetch: config.fetch,
-    codeSearch: config.codeSearch,
-    persistenceModes: [...OBSERVED_ROUTING_PERSISTENCE_MODES],
-    unsupportedPersistenceModes: [...RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES],
-    notes: [
-      "Observed routing is off unless outputRouter.enabled, outputRouter.observedRouting.enabled, and the individual producer/server are enabled.",
-      "redacted persistence is reserved for future work; unsupported redacted config falls back to metadata-only.",
-    ],
-  };
-}
-
-function migrationReport(rawConfig) {
-  const recommendations = collectMigrationRecommendations(rawConfig);
-  return {
-    applied: false,
-    requiresConfirmation: recommendations.length > 0,
-    recommendations,
-    note:
-      recommendations.length > 0
-        ? "Recommendations are informational only. Freeflow status/doctor does not rewrite .freeflow/config.json without explicit confirmation."
-        : "No migration recommendations detected.",
-  };
-}
-
-function collectMigrationRecommendations(rawConfig) {
-  const recommendations = [];
-  if (!isRecord(rawConfig)) {
-    return recommendations;
-  }
-
-  for (const key of Object.keys(rawConfig)) {
-    if (!TOP_LEVEL_CONFIG_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(key, "review", "Unrecognized top-level Freeflow config key; review before migrating."),
-      );
-    }
-  }
-
-  collectOutputRouterRecommendations(rawConfig.outputRouter, recommendations);
-  if (rawConfig.observedRouting !== undefined) {
-    recommendations.push(
-      recommendation("observedRouting", "move", "Move top-level observedRouting under outputRouter.observedRouting."),
-    );
-    collectObservedRoutingRecommendations(rawConfig.observedRouting, recommendations, "observedRouting");
-  }
-  if (rawConfig.scriptTransform !== undefined) {
-    recommendations.push(
-      recommendation("scriptTransform", "move", "Move top-level scriptTransform under outputRouter.scriptTransform."),
-    );
-    collectScriptTransformRecommendations(rawConfig.scriptTransform, recommendations, "scriptTransform");
-  }
-  return recommendations;
-}
-
-function collectOutputRouterRecommendations(value, recommendations) {
-  if (value === undefined) {
-    return;
-  }
-  if (!isRecord(value)) {
-    recommendations.push(
-      recommendation("outputRouter", "fix", "Expected object; remove or rewrite invalid outputRouter config."),
-    );
-    return;
-  }
-
-  for (const key of Object.keys(value)) {
-    if (!OUTPUT_ROUTER_CONFIG_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(`outputRouter.${key}`, "review", "Unrecognized outputRouter key; review before migrating."),
-      );
-    }
-  }
-
-  addDefaultRecommendation(recommendations, "outputRouter.enabled", value.enabled, DEFAULT_OUTPUT_ROUTER_ENABLED);
-  addDefaultRecommendation(recommendations, "outputRouter.profile", value.profile, DEFAULT_OUTPUT_ROUTER_PROFILE);
-  addDefaultRecommendation(
-    recommendations,
-    "outputRouter.postToolRouting",
-    value.postToolRouting,
-    DEFAULT_POST_TOOL_ROUTING,
-  );
-  addDefaultRecommendation(recommendations, "outputRouter.storagePolicy", value.storagePolicy, DEFAULT_STORAGE_POLICY);
-  collectThresholdRecommendations(value.thresholds, recommendations);
-  collectVaultRecommendations(value.vault, recommendations);
-  collectHintsRecommendations(value.hints, recommendations);
-  addLegacyMoveOrDefaultRecommendation(
-    recommendations,
-    "outputRouter.largeOutputBytes",
-    value.largeOutputBytes,
-    DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
-    "outputRouter.thresholds.largeOutputBytes",
-  );
-  addLegacyMoveOrDefaultRecommendation(
-    recommendations,
-    "outputRouter.largeOutputLines",
-    value.largeOutputLines,
-    DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
-    "outputRouter.thresholds.largeOutputLines",
-  );
-  addLegacyMoveOrDefaultRecommendation(
-    recommendations,
-    "outputRouter.vaultRoot",
-    value.vaultRoot,
-    DEFAULT_VAULT_ROOT,
-    "outputRouter.vault.root",
-  );
-  addLegacyMoveOrDefaultRecommendation(
-    recommendations,
-    "outputRouter.vaultRetentionDays",
-    value.vaultRetentionDays,
-    DEFAULT_VAULT_RETENTION.ttlDays,
-    "outputRouter.vault.retention.ttlDays",
-  );
-  collectObservedRoutingRecommendations(value.observedRouting, recommendations, "outputRouter.observedRouting");
-  collectScriptTransformRecommendations(value.scriptTransform, recommendations, "outputRouter.scriptTransform");
-
-  if (Object.keys(value).length === 0) {
-    recommendations.push(
-      recommendation("outputRouter", "remove", "Empty outputRouter object can be removed; built-in defaults apply."),
-    );
-  }
-}
-
-function collectThresholdRecommendations(value, recommendations) {
-  if (value === undefined) return;
-  if (!isRecord(value)) {
-    recommendations.push(
-      recommendation("outputRouter.thresholds", "fix", "Expected object with largeOutputBytes and largeOutputLines."),
-    );
-    return;
-  }
-  addDefaultRecommendation(
-    recommendations,
-    "outputRouter.thresholds.largeOutputBytes",
-    value.largeOutputBytes,
-    DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
-  );
-  addDefaultRecommendation(
-    recommendations,
-    "outputRouter.thresholds.largeOutputLines",
-    value.largeOutputLines,
-    DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
-  );
-}
-
-function collectVaultRecommendations(value, recommendations) {
-  if (value === undefined) return;
-  if (!isRecord(value)) {
-    recommendations.push(recommendation("outputRouter.vault", "fix", "Expected object with root and retention."));
-    return;
-  }
-  addDefaultRecommendation(recommendations, "outputRouter.vault.root", value.root, DEFAULT_VAULT_ROOT);
-  const retention = value.retention;
-  if (isRecord(retention)) {
-    addDefaultRecommendation(
-      recommendations,
-      "outputRouter.vault.retention.strategy",
-      retention.strategy,
-      DEFAULT_VAULT_RETENTION.strategy,
-    );
-    addDefaultRecommendation(
-      recommendations,
-      "outputRouter.vault.retention.ttlDays",
-      retention.ttlDays,
-      DEFAULT_VAULT_RETENTION.ttlDays,
-    );
-  } else if (retention !== undefined) {
-    recommendations.push(recommendation("outputRouter.vault.retention", "fix", "Expected retention object."));
-  }
-}
-
-function collectHintsRecommendations(value, recommendations) {
-  if (value === undefined) return;
-  if (!isRecord(value)) {
-    recommendations.push(
-      recommendation(
-        "outputRouter.hints",
-        "fix",
-        "Expected object with generatedPathGlobs/noisyCommandPatterns arrays.",
-      ),
-    );
-  }
-}
-
-function collectScriptTransformRecommendations(value, recommendations, path) {
-  if (value === undefined) {
-    return;
-  }
-  if (!isRecord(value)) {
-    recommendations.push(recommendation(path, "fix", `Expected object; remove or rewrite invalid ${path} config.`));
-    return;
-  }
-
-  for (const key of Object.keys(value)) {
-    if (!SCRIPT_TRANSFORM_CONFIG_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(`${path}.${key}`, "review", "Unrecognized scriptTransform key; review before migrating."),
-      );
-    }
-  }
-
-  addDefaultRecommendation(recommendations, `${path}.enabled`, value.enabled, DEFAULT_SCRIPT_TRANSFORM_CONFIG.enabled);
-  addDefaultRecommendation(recommendations, `${path}.sandbox`, value.sandbox, DEFAULT_SCRIPT_TRANSFORM_CONFIG.sandbox);
-  addDefaultRecommendation(recommendations, `${path}.network`, value.network, DEFAULT_SCRIPT_TRANSFORM_CONFIG.network);
-  addDefaultRecommendation(
-    recommendations,
-    `${path}.rawScriptPersistence`,
-    value.rawScriptPersistence,
-    DEFAULT_SCRIPT_TRANSFORM_CONFIG.rawScriptPersistence,
-  );
-
-  if (Object.keys(value).length === 0) {
-    recommendations.push(
-      recommendation(
-        path,
-        "remove",
-        "Empty scriptTransform object can be removed; script transform is disabled by default.",
-      ),
-    );
-  }
-}
-
-function collectObservedRoutingRecommendations(value, recommendations, path) {
-  if (value === undefined) {
-    return;
-  }
-  if (!isRecord(value)) {
-    recommendations.push(recommendation(path, "fix", `Expected object; remove or rewrite invalid ${path} config.`));
-    return;
-  }
-
-  for (const key of Object.keys(value)) {
-    if (!OBSERVED_ROUTING_CONFIG_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(`${path}.${key}`, "review", "Unrecognized observedRouting key; review before migrating."),
-      );
-    }
-  }
-
-  addDefaultRecommendation(recommendations, `${path}.enabled`, value.enabled, DEFAULT_OBSERVED_ROUTING_CONFIG.enabled);
-  addDefaultRecommendation(
-    recommendations,
-    `${path}.onRoutingFailure`,
-    value.onRoutingFailure,
-    DEFAULT_OBSERVED_ROUTING_CONFIG.onRoutingFailure,
-  );
-  collectObservedMcpRecommendations(value.mcp, recommendations, `${path}.mcp`);
-  collectObservedProducerRecommendations(value.web, `${path}.web`, recommendations);
-  collectObservedProducerRecommendations(value.fetch, `${path}.fetch`, recommendations);
-  collectObservedProducerRecommendations(value.codeSearch, `${path}.codeSearch`, recommendations);
-
-  if (Object.keys(value).length === 0) {
-    recommendations.push(
-      recommendation(
-        path,
-        "remove",
-        "Empty observedRouting object can be removed; observed routing is off by default.",
-      ),
-    );
-  }
-}
-
-function collectObservedMcpRecommendations(value, recommendations, path) {
-  if (value === undefined) {
-    return;
-  }
-  if (!isRecord(value)) {
-    recommendations.push(recommendation(path, "fix", "Expected object with explicit servers."));
-    return;
-  }
-
-  for (const key of Object.keys(value)) {
-    if (!OBSERVED_ROUTING_MCP_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(`${path}.${key}`, "review", "Unrecognized observedRouting.mcp key; review before migrating."),
-      );
-    }
-  }
-
-  if (value.servers !== undefined && !isRecord(value.servers)) {
-    recommendations.push(recommendation(`${path}.servers`, "fix", "Expected object keyed by MCP server id."));
-  }
-}
-
-function collectObservedProducerRecommendations(value, path, recommendations) {
-  if (value === undefined) {
-    return;
-  }
-  if (!isRecord(value)) {
-    recommendations.push(recommendation(path, "fix", "Expected object with enabled and persistence."));
-    return;
-  }
-
-  for (const key of Object.keys(value)) {
-    if (!OBSERVED_ROUTING_PRODUCER_KEYS.has(key)) {
-      recommendations.push(
-        recommendation(
-          `${path}.${key}`,
-          "review",
-          "Unrecognized observed routing producer key; review before migrating.",
-        ),
-      );
-    }
-  }
-}
-
-function addDefaultRecommendation(recommendations, path, value, defaultValue) {
-  if (value === undefined) {
-    return;
-  }
-  if (JSON.stringify(value) === JSON.stringify(defaultValue)) {
-    recommendations.push(
-      recommendation(
-        path,
-        "remove",
-        `Explicit default value ${JSON.stringify(defaultValue)} can be removed unless it records an intentional override.`,
-      ),
-    );
-  }
-}
-
-function addLegacyMoveOrDefaultRecommendation(recommendations, path, value, defaultValue, targetPath) {
-  if (value === undefined) {
-    return;
-  }
-  if (JSON.stringify(value) === JSON.stringify(defaultValue)) {
-    addDefaultRecommendation(recommendations, path, value, defaultValue);
-    return;
-  }
-  recommendations.push(recommendation(path, "move", `Move legacy ${path} to ${targetPath}.`));
-}
-
-function recommendation(path, action, message) {
-  return { path, action, message };
-}
-
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}