feat(migration): server-attested toolbox translation reports via the validation endpoint

[mikemcdougall]

Summary

Point the SDK's arcpy/toolbox translator at the server-side validation endpoint so translation reports become server-attested rather than SDK-local assertions.

honua-server adds POST /api/v{version}/admin/import/toolbox/translation/validate (honua-io/honua-server#3040, issue honua-io/honua-server#2145). It validates a translated toolbox mapping against the canonical GP process catalog and returns a per-tool classification (translated / partially-translated / unsupported) with the specific reasons a tool cannot be fully translated.

Today honua-migrate produces that verdict locally from the SDK's own view of the catalog. That means a report can disagree with the server that would actually run the job — the SDK can call a tool translated when the server's submit validator would reject it, or flag it unsupported when the server would accept it. Migration reports are used to decide whether a migration is viable, so a locally-derived verdict that drifts from the server is worse than no verdict.

Why this matters now

This is the last remaining tail of honua-io/honua-server#2145, which is the last open child of the GP porting epic honua-io/honua-server#1259. Everything else in that epic has landed. Once this ships, #2145 and #1259 can both close.

Explicitly NOT in scope — proprietary binary formats

This issue does not ask for binary .tbx parsing, and that must not be added. The current handling is correct and deliberate, and should stay:

• .pyt (plain-text Python toolbox) → parse_pyt_file ✅ supported
• .atbx (open ModelBuilder toolbox) → modelbuilder.parse_atbx_toolbox ✅ supported
• binary .tbx → UnsupportedToolboxError, with guidance to export to .atbx or .pyt

migration/modelbuilder.py states the standing position directly: "we never parse the proprietary binary .tbx". Honua's migration path for proprietary Esri containers is export-to-open-format, never reverse-engineering the container — the same rule that governs Esri locator files (.loc/.lox). UnsupportedToolboxError is a policy decision, not an unimplemented stub, and it should not be "fixed".

If anything, the actionable improvement here is making that refusal more helpful — see the optional item below.

Acceptance criteria

• honua-migrate translate (and the corresponding library entrypoint) can submit a translated mapping to the server validation endpoint and incorporate the server's per-tool classification into the report.
• The report distinguishes a server-attested verdict from a local-only verdict, so a reader can tell which one they are looking at. A local fallback must never be presented as attested.
• Offline / no-server operation still works and degrades to the local verdict with an explicit marker — this must not become a hard dependency on a reachable server.
• Where the server and local verdicts disagree, the server's verdict wins and the disagreement is surfaced rather than silently overwritten (this is the signal that the SDK's catalog view has drifted).
• Auth: the endpoint is under the admin import group, so the existing SDK admin credential/token path is used; no new auth mechanism.
• Tests cover: attested success, server-vs-local disagreement, server unreachable (offline fallback), and an unauthorized/failed call not silently degrading into a false "attested" claim.
• Optional but useful: when UnsupportedToolboxError is raised for a binary .tbx, include the concrete ArcGIS Pro export steps to produce a .pyt/.atbx, so the error is a migration instruction rather than a dead end.

Dependencies

• Blocked on feat: add server-side arcpy/toolbox translation lane validation surface (#2145) honua-server#3040 landing (the endpoint does not exist on trunk yet). Worth confirming the merged route and response shape before implementing, rather than coding against the PR.

Cross-links

• arcpy / toolbox (.tbx/.pyt) translation lane honua-server#2145 — arcpy / toolbox translation lane (parent)
• Epic: port Esri geoprocessing (GP) services to Honua honua-server#1259 — Epic: port Esri geoprocessing (GP) services to Honua
• feat: add server-side arcpy/toolbox translation lane validation surface (#2145) honua-server#3040 — server-side translation validation endpoint