AI-1386 branched storage shading

[vita-stejskal]

release notes

• Version: v1.20.3 (was v1.20.2)
• Branch-aware storage tools (prod/dev shading)
  • get_bucket, list_buckets, get_table, list_tables now correctly resolve and merge prod and current-branch dev entities.
  • Normalized IDs to prod IDs in outputs; dev entities are presented as their prod counterparts when applicable.
  • For combined results, size and counts are approximated by summing prod + dev values.
  • UI links are now branch-aware (dev links when on a dev branch) while preserving prod names where appropriate.
• Consistent not-found error handling
  • 404s from Storage API for bucket and table tools are now surfaced as ValueError with concise messages:
    • 'Bucket not found: {bucket_id}'
    • 'Table not found: {table_id}'
  • Tests updated to reflect the standardized error semantics.
• Link improvements
  • get_table_links now accepts bucket_name ensuring bucket links display human-friendly names.
• Type hint refinement
  • Minor type signature cleanup in get_metadata_property.

plans for customer communication

• Breaking behavior note: (local code) Callers expecting httpx.HTTPStatusError on not-found for bucket and table tools must handle ValueError instead.
• Announce branch-aware behavior changes for storage tools (IDs normalized to prod; links now branch-aware; size/count aggregation).
• Update any downstream usage docs and examples accordingly.

impact analysis

• Potential breaking change: (local code) Exception type for 404 moves from httpx.HTTPStatusError to ValueError in bucket and table tools.
• Output shape/semantics:
  • Bucket/table IDs in dev contexts are normalized to prod IDs; consumers comparing raw IDs may see differences.
  • Size/count fields for combined prod+dev are summed (approximate).
  • In list_buckets, per-bucket links are omitted (project-level link still provided).
• Low risk beyond the above; robust tests were added/updated.

change type

Improvement/Fix

justification

• Improve behavior in dev branches and unify prod/dev visibility.
• Provide simpler error messages for not-found scenarios.
• Improve link labeling and routing for better UX.

deployment plan

• Merge PR to main and tag v1.20.3.

rollback plan

• Revert to v1.20.2.

post release support plan

• Monitor logs for ValueError handling in clients and support tickets referencing not-found cases.
• Smoke test storage tools (get_bucket, list_buckets, get_table, list_tables) on prod and dev branches.
• Notify integrators about the exception type change and ID normalization behavior.