fix(combos): PUT/DELETE error-shape standardization + stable flow node IDs (refs #4774, closes #4874)

[KooshaPari]

What

Closes two follow-ups to the combo 400 / flow-canvas issue:

1. PUT /api/combos/{id} returns 400 with raw-string body, no machine-readable error code (closes bug: POST /api/combos/{id} returns 400 with raw-string body, no machine-readable error code #4871, superseded by fix(combos): auto-promote zeroLatencyOptimizationsEnabled so legacy configs (pre-3.8.33 fallbackCompressionMode="lite") round-trip on the first GUI edit #4774 for the original 400 — this PR keeps the standardized error shape in case the underlying validation paths are hit by other inputs)
2. 'Node cannot be found in the current page' when switching between two runs of the same combo (closes bug: 'Node cannot be found in the current page' when switching between two runs of the same combo #4874)

Why (per Diego's review on #4871)

Diego confirmed:

• POST /api/combos/{id} is not a defined handler — only GET/PUT/DELETE are.
• The original 400 root cause was fixed by fix(combos): auto-promote zeroLatencyOptimizationsEnabled so legacy configs (pre-3.8.33 fallbackCompressionMode="lite") round-trip on the first GUI edit #4774 (merged in v3.8.35, commit 759265877feaa01f11d8ee50651ae24b07b5ba96) — a transform-based auto-promote in src/shared/validation/schemas/combo.ts lines 189-209.
• The combo API does return structured { "error": ... } bodies on the current code, not raw strings.

This PR now keeps the shape of the structured error consistent with the rest of the v3.8.34 API surface (canonical { error: { code, message, requestId, details } }) and adds the run-scoped node-ID fix for the flow canvas.

Changes

• src/shared/constants/errorCodes.ts — +8 stable codes COMBO_001..COMBO_008
• src/lib/api/comboErrorResponse.ts (new) — createComboErrorResponse(code, ...) helper with x-request-id passthrough and DAG-message sanitization
• src/app/api/combos/[id]/route.ts — uses helper for all 4xx paths; DAG messages no longer echo raw user strings
• src/app/api/combos/route.ts — same helper for the collection route
• src/shared/components/flow/FlowCanvas.tsx — ref-generation counter incremented on every react-flow update; rfInstance.current = null on unmount; ref type widened to MutableRefObject<ReactFlowInstance | null>
• src/app/(dashboard)/dashboard/combos/live/comboFlowModel.ts — namespace every node/edge id with r<startedAt>-<sanitizeId(comboName)>: so two runs of the same combo are disjoint graphs
• tests/unit/api/combo-error-response.test.ts (new) — 116 assertions covering all 8 codes, requestId passthrough, DAG sanitization
• vitest.config.ts — include tests/unit/**/*.test.ts (was .tsx-only)

Tests

npx vitest run --no-coverage tests/unit/api/combo-error-response.test.ts

Result: all 116 assertions pass.

npx tsc -p tsconfig.typecheck-core.json

Result: 0 type errors in modified files.

Acceptance

• Every 4xx response in /api/combos/* matches the canonical error shape
• requestId is the x-request-id header (or a generated UUID)
• DAG validation messages do not echo raw user-supplied strings
• Unit tests cover all 8 codes + sanitization
• FlowCanvas unmount clears the ref
• Combo node IDs are run-scoped

Related

• fix(combos): auto-promote zeroLatencyOptimizationsEnabled so legacy configs (pre-3.8.33 fallbackCompressionMode="lite") round-trip on the first GUI edit #4774 (v3.8.35) — root-cause fix for the original 400
• bug: POST /api/combos/{id} returns 400 with raw-string body, no machine-readable error code #4871 (closed/duplicate) — Diego's review clarified the underlying issue
• fix(combos): skip composite-tiers validation on non-graph PUT updates #4880 (v3.8.36) — related combo API fix (skip composite-tiers on non-graph PUT)
• Audit: plans/2026-06-23-omniroute-v3.8.34-deep-audit.md

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[KooshaPari]

@diegosouzapw - pinging for review on this one. Targets release/v3.8.34 and fixes the combo 400 + FlowCanvas 'Node cannot be found' bugs from your console log. Closes #4871 + #4874. Tests: 116/116 vitest assertions pass. tsc: 0 errors. The DAG sanitization removes the user-string echo that gemini flagged on prior review items. If anything in the COMBO_001..008 code list should be re-shaped, please flag in the inline review - happy to iterate.

[KooshaPari]

Thanks Diego for the review on #4871 — your pointer to #4774 (the transform-based auto-promote in src/shared/validation/schemas/combo.ts:189-209) is the actual root-cause fix for the original 400.

I've updated the PR:

• Title: fix(combos): PUT/DELETE error-shape standardization + stable flow node IDs (refs #4774, closes #4874) — the bug is on PUT/DELETE, not POST (POST isn't a defined handler on /api/combos/{id}).
• Body: explains the layering — fix(combos): auto-promote zeroLatencyOptimizationsEnabled so legacy configs (pre-3.8.33 fallbackCompressionMode="lite") round-trip on the first GUI edit #4774 fixes the v3.8.33 400 root cause; this PR keeps the structured error shape (canonical { error: { code, message, requestId, details } }) consistent with the rest of v3.8.34, in case other inputs hit those validation paths.
• Flow canvas (Bug feat(versioning): set initial version to 0.0.1 and restore dynamic model import #4): still in scope — stable run-scoped node IDs, ref-generation counter, ref cleared on unmount. That's the unrecoverable-from-cache part of the bug.

If you'd prefer the error-shape piece be split out (e.g. wait for #4774 to land and see if it's still needed), or if the flow canvas fix should be its own PR, let me know — happy to refactor. Otherwise, this is ready for review on the FlowCanvas half and a sanity check on whether the COMBO_001..008 codes are useful for the live tree.

[KooshaPari]

Closing as duplicate — upstream v3.8.35 ships src/shared/constants/errorCodes.ts with stable IDs (and tests/unit/api/combo-error-response.test.ts covers the surface). My PR was the same intent from a different angle; no need to merge a second implementation.

Tracking continues on the 6 other still-unique PRs (#4880, #4881, #4888, #4902, #4903, #4904), which address gaps upstream hasn't filled yet.