@nodaro/shared 2.2.1 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/normalize-model-input.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  normalizeModelInput,
+  validateModelInput,
+  defaultResolutionFor,
+} from "../model-catalog.js"
+
+/**
+ * `normalizeModelInput` is the correcting twin of `validateModelInput`, used at
+ * persistence and execution boundaries where rejecting a fixable value would
+ * abort a run (and take every already-billed sibling node with it).
+ *
+ * The load-bearing invariant is the round-trip: whatever the normalizer emits
+ * MUST satisfy the validator. If those two ever disagree, a "normalized" node
+ * still 400s upstream and the whole exercise is theatre.
+ */
+
+describe("normalizeModelInput", () => {
+  it("leaves an already-valid combination untouched", () => {
+    const out = normalizeModelInput("gpt-image-2", { aspectRatio: "16:9", resolution: "2K" })
+    expect(out.aspectRatio).toBe("16:9")
+    expect(out.resolution).toBe("2K")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("snaps the aspect ratio that aborted the 2026-08-09 run", () => {
+    // gpt-image (GPT Image 1.5) accepts 1:1 / 3:2 / 2:3 only — KIE rejects 16:9.
+    const out = normalizeModelInput("gpt-image", { aspectRatio: "16:9" })
+    expect(out.aspectRatio).not.toBe("16:9")
+    expect(MODEL_CATALOG["gpt-image"].aspectRatios).toContain(out.aspectRatio!)
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].from).toBe("16:9")
+    // The reason is user-facing — it must name the alternatives.
+    expect(out.adjustments[0].reason).toContain("3:2")
+  })
+
+  it("drops a lever the model does not have at all", () => {
+    // Same node also carried resolution "2K"; GPT Image 1.5 has no resolution.
+    const out = normalizeModelInput("gpt-image", { resolution: "2K" })
+    expect(out.resolution).toBeUndefined()
+    expect(out.adjustments[0]).toMatchObject({ field: "resolution", from: "2K", to: undefined })
+  })
+
+  it("canonicalizes an equivalent spelling instead of re-pricing the node", () => {
+    // Flux 2 resolution reaches the payload builder as a bare megapixel count
+    // ("1"); the catalog lists the display form ("1 MP"). Treating that as
+    // invalid would snap it to the 2 MP default — a silent price increase on a
+    // node the user configured correctly.
+    const out = normalizeModelInput("flux-2-pro", { resolution: "1" })
+    expect(out.resolution).toBe("1 MP")
+    expect(out.adjustments).toEqual([])
+    // Case drift is the same class of non-change.
+    expect(normalizeModelInput("nano-banana-pro", { resolution: "4k" }).resolution).toBe("4K")
+    expect(normalizeModelInput("nano-banana-pro", { resolution: "4k" }).adjustments).toEqual([])
+  })
+
+  it("does NOT treat a different unit as equivalent", () => {
+    // "1" must not quietly satisfy a 1K/2K/4K model — those are different scales.
+    const out = normalizeModelInput("nano-banana-pro", { resolution: "1" })
+    expect(out.resolution).not.toBe("1")
+    expect(MODEL_CATALOG["nano-banana-pro"].resolutions).toContain(out.resolution!)
+    expect(out.adjustments).toHaveLength(1)
+  })
+
+  it("prefers the Flux 2 default over the cheapest option when snapping", () => {
+    // options[0] is "0.5 MP" — snapping there would silently downgrade quality.
+    const out = normalizeModelInput("flux-2-pro", { resolution: "2K" })
+    expect(out.resolution).toBe(defaultResolutionFor("flux-2-pro"))
+    expect(out.resolution).toBe("2 MP")
+  })
+
+  it("applies the gpt-image-2 cross-field rules after snapping", () => {
+    expect(normalizeModelInput("gpt-image-2", { aspectRatio: "auto", resolution: "4K" }).resolution).toBe("1K")
+    expect(normalizeModelInput("gpt-image-2", { aspectRatio: "1:1", resolution: "4K" }).resolution).toBe("2K")
+  })
+
+  it("passes unknown model ids through untouched (the Zod enum owns those)", () => {
+    const out = normalizeModelInput("totally-fake-model", { aspectRatio: "21:9" })
+    expect(out.aspectRatio).toBe("21:9")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("is idempotent — normalizing twice changes nothing the second time", () => {
+    const once = normalizeModelInput("gpt-image", { aspectRatio: "16:9", resolution: "2K" })
+    const twice = normalizeModelInput("gpt-image", {
+      aspectRatio: once.aspectRatio,
+      resolution: once.resolution,
+    })
+    expect(twice.adjustments).toEqual([])
+    expect(twice.aspectRatio).toBe(once.aspectRatio)
+  })
+
+  // -------------------------------------------------------------------------
+  // The invariant. Runs over the WHOLE catalog so a model added later is
+  // covered by default rather than by anyone remembering to extend a list.
+  // -------------------------------------------------------------------------
+  it("INVARIANT: normalized output always satisfies validateModelInput", () => {
+    // Deliberately hostile inputs — a value from some OTHER model's allow-list
+    // is exactly what a provider switch or a non-UI author leaves behind.
+    const hostile = [
+      { aspectRatio: "16:9" },
+      { aspectRatio: "auto" },
+      { aspectRatio: "1:1", resolution: "4K" },
+      { aspectRatio: "21:9", resolution: "2K", quality: "high" },
+      { resolution: "0.5 MP" },
+      { quality: "basic" },
+      { duration: 7 },
+      { aspectRatio: "9:21", resolution: "8K", quality: "TURBO", duration: 999 },
+    ]
+
+    const failures: string[] = []
+    for (const modelId of Object.keys(MODEL_CATALOG)) {
+      for (const input of hostile) {
+        const out = normalizeModelInput(modelId, input)
+        const issue = validateModelInput(modelId, {
+          aspectRatio: out.aspectRatio,
+          resolution: out.resolution,
+          quality: out.quality,
+          duration: out.duration,
+        })
+        if (issue) {
+          failures.push(
+            `${modelId} ← ${JSON.stringify(input)} → ${JSON.stringify({
+              aspectRatio: out.aspectRatio,
+              resolution: out.resolution,
+              quality: out.quality,
+              duration: out.duration,
+            })}: ${issue.message}`,
+          )
+        }
+      }
+    }
+
+    expect(failures, `normalizeModelInput emitted values validateModelInput rejects:\n${failures.join("\n")}`).toEqual([])
+  })
+
+  it("INVARIANT: every adjustment names a real change", () => {
+    for (const modelId of Object.keys(MODEL_CATALOG)) {
+      const out = normalizeModelInput(modelId, {
+        aspectRatio: "21:9",
+        resolution: "8K",
+        quality: "high",
+        duration: 999,
+      })
+      for (const adj of out.adjustments) {
+        expect(adj.from, `${modelId}/${adj.field} reported a no-op adjustment`).not.toEqual(adj.to)
+        expect(adj.reason.length).toBeGreaterThan(0)
+      }
+    }
+  })
+})

package/src/__tests__/normalize-node-params.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest"
+import { normalizeNodeModelParams, MODEL_PARAM_NODE_TYPES } from "../normalize-node-params.js"
+
+/**
+ * Write-boundary guard for agent/import-authored graphs. The config panel's
+ * provider-aware dropdown and its stale-value snap are React effects — they
+ * only run for a node whose panel or hover strip is mounted, so a node written
+ * straight into workflow JSON never meets either.
+ */
+
+const node = (id: string, type: string, data: Record<string, unknown>) => ({
+  id,
+  type,
+  position: { x: 0, y: 0 },
+  data,
+})
+
+describe("normalizeNodeModelParams", () => {
+  it("heals the exact node that aborted the 2026-08-09 run", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("node_8", "generate-image", { provider: "gpt-image", aspectRatio: "16:9", resolution: "2K" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    expect(d.aspectRatio).not.toBe("16:9")
+    expect(d.resolution).toBeUndefined() // GPT Image 1.5 has no resolution lever
+    expect(adjustments.map((a) => a.field).sort()).toEqual(["aspectRatio", "resolution"])
+    expect(adjustments[0].nodeId).toBe("node_8")
+    expect(adjustments[0].provider).toBe("gpt-image")
+  })
+
+  it("leaves the sibling nodes that were already valid completely alone", () => {
+    // Same workflow, the five nodes that generated fine — must be untouched,
+    // and returned BY REFERENCE so a delta/CAS save sees no spurious change.
+    const input = [
+      node("a", "generate-image", { provider: "gpt-image-2", aspectRatio: "16:9", resolution: "2K" }),
+      node("b", "generate-image", { provider: "grok", aspectRatio: "16:9" }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes[0]).toBe(input[0])
+    expect(nodes[1]).toBe(input[1])
+  })
+
+  it("never mutates the caller's node objects", () => {
+    const input = [node("n1", "generate-image", { provider: "gpt-image", aspectRatio: "16:9" })]
+    const before = JSON.parse(JSON.stringify(input))
+    normalizeNodeModelParams(input)
+    expect(input).toEqual(before)
+  })
+
+  it("ignores node types that carry no catalog-governed params", () => {
+    const input = [
+      node("t1", "text-prompt", { provider: "gpt-image", aspectRatio: "16:9" }),
+      node("v1", "image-to-video", { provider: "veo3", aspectRatio: "21:9" }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes).toEqual(input)
+    expect(MODEL_PARAM_NODE_TYPES.has("image-to-video")).toBe(false)
+  })
+
+  it("skips multi-provider nodes rather than guessing an intersection", () => {
+    const input = [
+      node("m1", "generate-image", {
+        providers: ["gpt-image", "gpt-image-2"],
+        provider: "gpt-image",
+        aspectRatio: "16:9",
+      }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes[0]).toBe(input[0])
+  })
+
+  it("survives malformed nodes without throwing", () => {
+    const input = [
+      { id: "x", type: "generate-image" },
+      { id: "y", type: "generate-image", data: null },
+      { id: "z", type: "generate-image", data: { provider: 42 } },
+      { type: "generate-image", data: { provider: "gpt-image", aspectRatio: "16:9" } },
+    ] as Array<{ id?: unknown; type?: unknown; data?: unknown }>
+    expect(() => normalizeNodeModelParams(input)).not.toThrow()
+    const { adjustments } = normalizeNodeModelParams(input)
+    // The last entry has no id but IS healable — it reports under a placeholder.
+    expect(adjustments.every((a) => typeof a.nodeId === "string")).toBe(true)
+  })
+
+  it("is idempotent — a second pass reports nothing", () => {
+    const first = normalizeNodeModelParams([
+      node("n1", "generate-image", { provider: "gpt-image", aspectRatio: "16:9", resolution: "2K" }),
+    ])
+    const second = normalizeNodeModelParams(first.nodes)
+    expect(second.adjustments).toEqual([])
+  })
+})

package/src/index.ts

@@ -693,6 +693,8 @@ export {
   creditRangesAll,
   modelIdsByKindMode,
   buildModelMenu,
+  normalizeModelInput,
+  defaultResolutionFor,
 } from "./model-catalog.js"
 export type {
   ModelCatalogEntry,
@@ -704,6 +706,8 @@ export type {
   ValidationField,
   LabeledOption,
   ModelMenuOption,
+  ModelInputAdjustment,
+  NormalizedModelInput,
 } from "./model-catalog.js"
 
 export {
@@ -876,6 +880,13 @@ export type { VoiceChangerModel } from "./voice-changer-models.js"
 
 // --- Node presets ---
 export { EXECUTION_DATA_KEYS, TRANSIENT_RUNTIME_KEYS, stripTransientRuntimeData } from "./node-runtime-keys.js"
+
+export {
+  MODEL_PARAM_NODE_TYPES,
+  normalizeNodeModelParams,
+  describeNodeAdjustments,
+} from "./normalize-node-params.js"
+export type { NodeParamAdjustment, NormalizedNodes } from "./normalize-node-params.js"
 export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, presetDataMatches } from "./node-preset-extract.js"
 
 // --- Factory prompt-snippets (reusable inline prompt fragments) ---

package/src/model-catalog.ts

@@ -28,6 +28,8 @@
  *   `docs/choosing-models.md` guide. CI (`gen:skills:check`) fails on drift.
  */
 
+import { isFlux2Model } from "./flux2-pricing.js"
+
 export type ModelKind = "image" | "video" | "audio"
 
 export type ModelMode =
@@ -2385,6 +2387,165 @@ export function validateModelInput(
   return null
 }
 
+/**
+ * The resolution a Flux 2 model should land on when its stored value is absent
+ * or invalid. Flux 2 exposes ascending megapixel options ("0.5 MP"…"4 MP"), so
+ * snapping to `options[0]` would silently downgrade every node to the cheapest
+ * tier; each variant has a sensible mid default instead. Returns undefined for
+ * every non-Flux-2 model (they snap to `options[0]` normally).
+ */
+export function defaultResolutionFor(modelId: string): string | undefined {
+  if (!isFlux2Model(modelId)) return undefined
+  return modelId === "flux-2-klein" ? "1 MP" : "2 MP"
+}
+
+/**
+ * True when two option values denote the same setting written differently.
+ * Handles case/whitespace ("4k" vs "4K") and the megapixel form Flux 2 stores
+ * as a bare count ("1") against the catalog's display form ("1 MP").
+ */
+function sameOptionValue(a: string | number, b: string | number): boolean {
+  if (a === b) return true
+  const norm = (v: string | number) =>
+    String(v).trim().toLowerCase().replace(/\s*mp$/, "").replace(/\s+/g, "")
+  const na = norm(a)
+  const nb = norm(b)
+  if (na === nb) return true
+  // Numeric equivalence so "1" matches "1.0" and " 1 MP".
+  const fa = Number(na)
+  const fb = Number(nb)
+  return Number.isFinite(fa) && Number.isFinite(fb) && fa === fb
+}
+
+/** One correction `normalizeModelInput` made, for disclosure to the user. */
+export interface ModelInputAdjustment {
+  field: "aspectRatio" | "resolution" | "quality" | "duration"
+  /** The value that was asked for. */
+  from: string | number
+  /** What it became — `undefined` means the lever was dropped entirely. */
+  to: string | number | undefined
+  reason: string
+}
+
+export interface NormalizedModelInput {
+  aspectRatio?: string
+  resolution?: string
+  quality?: string
+  duration?: number
+  /** Empty when the input was already valid. */
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * Coerce a model's parameters into a combination the model actually accepts.
+ *
+ * The correcting twin of `validateModelInput`. Validation is right when a
+ * human/agent is composing a single call and can retry (MCP verbs do this).
+ * It is the WRONG answer at a persistence or execution boundary: rejecting
+ * there turns a fixable typo into a failed run — and a failed run takes every
+ * already-generated, already-billed sibling node down with it. Incident
+ * 2026-08-09: one node carrying `gpt-image` + `16:9` (a pair the config panel
+ * cannot produce, written straight into workflow JSON by a non-UI author)
+ * aborted a run whose five other nodes had already produced images.
+ *
+ * Rules, mirroring the config panels' provider-change snap:
+ *  - Model has no such lever → drop the value (sending it 400s upstream).
+ *  - Value outside the model's allow-list → snap to the model's default
+ *    (`defaultResolutionFor`) or the first valid option.
+ *  - Then apply cross-field constraints that only hold for certain models.
+ *
+ * Unknown model ids pass through untouched — the route's Zod model enum is the
+ * right gate for those, exactly as in `validateModelInput`.
+ *
+ * Every correction is reported in `adjustments` so callers can disclose what
+ * changed rather than silently handing back something else.
+ */
+export function normalizeModelInput(
+  modelId: string,
+  input: {
+    aspectRatio?: string
+    resolution?: string
+    quality?: string
+    duration?: number
+  },
+): NormalizedModelInput {
+  const m = MODEL_CATALOG[modelId]
+  const adjustments: ModelInputAdjustment[] = []
+  if (!m) return { ...input, adjustments }
+
+  const out: NormalizedModelInput = { ...input, adjustments }
+
+  const snap = <T extends string | number>(
+    field: ModelInputAdjustment["field"],
+    value: T | undefined,
+    allowed: readonly T[] | undefined,
+    preferred?: T,
+  ): T | undefined => {
+    if (value === undefined) return undefined
+    if (!allowed || allowed.length === 0) {
+      adjustments.push({
+        field,
+        from: value,
+        to: undefined,
+        reason: `${m.label} has no ${field} setting — the value was dropped.`,
+      })
+      return undefined
+    }
+    if (allowed.includes(value)) return value
+    // Same value, different spelling — canonicalize instead of "correcting".
+    // Stored data is not uniform with the catalog's display form: Flux 2 bills
+    // off a bare megapixel count ("1") while the catalog lists "1 MP", and "4k"
+    // appears alongside "4K". Treating those as invalid would snap a perfectly
+    // good value to a DIFFERENT tier — i.e. silently re-price the node — which
+    // is worse than the bug this function exists to fix.
+    const canonical = allowed.find((a) => sameOptionValue(a, value))
+    if (canonical !== undefined) return canonical
+    const next = preferred !== undefined && allowed.includes(preferred) ? preferred : allowed[0]
+    adjustments.push({
+      field,
+      from: value,
+      to: next,
+      reason: `${m.label} does not support ${field} "${value}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+    })
+    return next
+  }
+
+  out.aspectRatio = snap("aspectRatio", input.aspectRatio, m.aspectRatios)
+  out.resolution = snap(
+    "resolution",
+    input.resolution,
+    m.resolutions,
+    defaultResolutionFor(modelId),
+  )
+  out.quality = snap("quality", input.quality, m.qualities)
+  out.duration = snap("duration", input.duration, m.durations)
+
+  // Cross-field constraints — a pair that is individually valid but jointly
+  // rejected upstream. GPT Image 2 (per docs.kie.ai): `auto` requires 1K, and
+  // 1:1 cannot go to 4K. Applied last so it sees the already-snapped values.
+  if (modelId === "gpt-image-2" || modelId === "gpt-image-2-i2i") {
+    if (out.aspectRatio === "auto" && out.resolution !== undefined && out.resolution !== "1K") {
+      adjustments.push({
+        field: "resolution",
+        from: out.resolution,
+        to: "1K",
+        reason: `${m.label} only renders 1K at the "auto" aspect ratio.`,
+      })
+      out.resolution = "1K"
+    } else if (out.aspectRatio === "1:1" && out.resolution === "4K") {
+      adjustments.push({
+        field: "resolution",
+        from: "4K",
+        to: "2K",
+        reason: `${m.label} cannot render 4K at a 1:1 aspect ratio.`,
+      })
+      out.resolution = "2K"
+    }
+  }
+
+  return out
+}
+
 // =============================================================================
 // Frontend picker helpers — return `{value, label}[]` shapes that the
 // existing config-panel components expect, derived from the catalog so we

package/src/normalize-node-params.ts

@@ -0,0 +1,126 @@
+/**
+ * Workflow-node parameter normalization.
+ *
+ * The config panels already prevent an impossible provider/parameter pair from
+ * being *selected*: their dropdowns are provider-aware and a fail-safe effect
+ * snaps stale values when the provider changes. But both of those are React
+ * effects — they only run when that specific node's panel or hover strip is
+ * mounted. A node written straight into workflow JSON by a non-UI author (an
+ * agent, an import, a template) is never seen by either, so its invalid pair
+ * survives all the way to the provider call.
+ *
+ * That is the 2026-08-09 incident: one `generate-image` node carrying
+ * `gpt-image` + `16:9` (GPT Image 1.5 renders 1:1 / 3:2 / 2:3 only) reached KIE,
+ * got rejected, and aborted a run whose five sibling nodes had already produced
+ * — and billed for — their images.
+ *
+ * This module is the write-boundary guard: it heals the node instead of
+ * rejecting it, so the user sees a valid value on the canvas rather than a
+ * failed run. It reads exclusively from `MODEL_CATALOG`, so a model added later
+ * is covered without touching this file.
+ */
+
+import { normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.js"
+
+/**
+ * Node types whose `data` carries catalog-governed model parameters under the
+ * shape this module understands (`provider` + aspectRatio/resolution/quality).
+ *
+ * IMAGE ONLY, deliberately. The video nodes route several of these fields
+ * through mode-dependent defaults (`"adaptive"` for Seedance/Hailuo, duration
+ * composites tied to pricing) that this flat normalizer would flatten wrongly;
+ * they get their own pass once those defaults are catalog-derived too.
+ */
+export const MODEL_PARAM_NODE_TYPES: ReadonlySet<string> = new Set([
+  "generate-image",
+  "image-to-image",
+])
+
+export interface NodeParamAdjustment extends ModelInputAdjustment {
+  nodeId: string
+  provider: string
+}
+
+export interface NormalizedNodes<T> {
+  nodes: T[]
+  /** Empty when nothing needed correcting. */
+  adjustments: NodeParamAdjustment[]
+}
+
+interface NodeLike {
+  id?: unknown
+  type?: unknown
+  data?: unknown
+}
+
+/**
+ * Return `nodes` with every catalog-governed image parameter coerced into a
+ * combination its provider actually accepts, plus the list of what changed.
+ *
+ * Immutable: nodes that need no correction are returned by reference, and a
+ * corrected node is a fresh object (never a mutation of the caller's input).
+ *
+ * Multi-provider nodes (`data.providers` holding 2+ entries) are SKIPPED: the
+ * valid set there is the intersection across every selected provider, and when
+ * a stored value falls outside it there is no single defensible replacement —
+ * picking one provider's default would silently misconfigure the others. Those
+ * nodes are still guarded interactively by the panel's intersection dropdown.
+ */
+export function normalizeNodeModelParams<T extends NodeLike>(
+  nodes: readonly T[],
+): NormalizedNodes<T> {
+  const adjustments: NodeParamAdjustment[] = []
+  const out = nodes.map((node) => {
+    const type = typeof node.type === "string" ? node.type : ""
+    if (!MODEL_PARAM_NODE_TYPES.has(type)) return node
+
+    const data = node.data
+    if (!data || typeof data !== "object" || Array.isArray(data)) return node
+    const d = data as Record<string, unknown>
+
+    const multi = Array.isArray(d.providers) ? (d.providers as unknown[]) : []
+    if (multi.length > 1) return node
+
+    const provider =
+      typeof d.provider === "string"
+        ? d.provider
+        : typeof multi[0] === "string"
+          ? (multi[0] as string)
+          : undefined
+    if (!provider) return node
+
+    const normalized = normalizeModelInput(provider, {
+      aspectRatio: typeof d.aspectRatio === "string" ? d.aspectRatio : undefined,
+      resolution: typeof d.resolution === "string" ? d.resolution : undefined,
+      quality: typeof d.quality === "string" ? d.quality : undefined,
+    })
+    if (normalized.adjustments.length === 0) return node
+
+    const nodeId = typeof node.id === "string" ? node.id : "(unknown node)"
+    for (const adj of normalized.adjustments) {
+      adjustments.push({ ...adj, nodeId, provider })
+    }
+
+    // Only the three governed keys are rewritten; everything else on the node
+    // is passed through untouched. A dropped lever is written as `undefined`
+    // rather than deleted so the shape stays stable for downstream readers.
+    return {
+      ...node,
+      data: {
+        ...d,
+        aspectRatio: normalized.aspectRatio,
+        resolution: normalized.resolution,
+        quality: normalized.quality,
+      },
+    }
+  })
+
+  return { nodes: out, adjustments }
+}
+
+/** One-line-per-change summary, for surfacing back to an agent or a log. */
+export function describeNodeAdjustments(adjustments: readonly NodeParamAdjustment[]): string[] {
+  return adjustments.map(
+    (a) => `${a.nodeId} (${a.provider}): ${a.field} "${a.from}" → ${a.to === undefined ? "removed" : `"${a.to}"`} — ${a.reason}`,
+  )
+}