@hassangameryt/freeflow 0.3.0 → 0.5.0

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

@@ -0,0 +1,791 @@
+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);
+}