IHS-119: Fix upsert not working for numberpool and attribute in hfid

[solababs]

Why

node.save(allow_upsert=True) on a node whose human-friendly identifier (HFID) contains a CoreNumberPool-sourced attribute crashes with "invalid literal for int() with base 10: 'VLAN ID Pool - Test'". The backend upsert resolver tries to use the unresolved pool reference as an HFID component, but the integer value is not assigned until after the server creates the node — making the upsert semantically impossible.

This PR adds a client-side guard that detects the pattern and raises a descriptive ValidationError before any network call is made.

Closes #339

How to test

cd python_sdk

# All four upsert guard tests
uv run pytest tests/unit/sdk/pool/test_attribute_from_pool.py -v -k "upsert"

Checklist

• Tests added/updated
• Changelog entry added (python_sdk/changelog/339.fixed.md)
• External docs updated (docs/docs/python-sdk/guides/resource-manager.mdx)
• Internal .md docs updated (internal knowledge and AI code tools knowledge)

---

Summary by cubic

Prevented crashes when calling save(allow_upsert=True) on nodes whose HFID includes a CoreNumberPool-sourced attribute by adding a client-side check that raises a clear ValidationError. Addresses IHS-119.

• Bug Fixes
  • Added a guard in InfrahubNode.save() (async and sync) to detect pool-backed HFID attributes and raise ValidationError before any request when allow_upsert=True and no id is set.
  • Upsert still works when id is provided or when the pool-backed attribute is not part of the HFID.
  • Added unit tests for guard and bypass cases; updated Resource Manager guide with a warning, examples, and alternatives; added changelog entry.

^{Written for commit 98047b9. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	98047b9
Status:	✅  Deploy successful!
Preview URL:	https://1644a246.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://sb-12052026-fix-upsert-numbe.infrahub-sdk-python.pages.dev

View logs

[codecov]

Codecov Report

❌ Patch coverage is 78.94737% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
infrahub_sdk/node/node.py	78.94%	3 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##           stable    #1014      +/-   ##
==========================================
+ Coverage   81.56%   81.59%   +0.02%     
==========================================
  Files         134      134              
  Lines       11442    11460      +18     
  Branches     1730     1736       +6     
==========================================
+ Hits         9333     9351      +18     
- Misses       1564     1565       +1     
+ Partials      545      544       -1     

Flag	Coverage Δ
integration-tests	41.58% <63.15%> (+0.09%)	⬆️
python-3.10	54.58% <31.57%> (+<0.01%)	⬆️
python-3.11	54.58% <31.57%> (+<0.01%)	⬆️
python-3.12	54.58% <31.57%> (+0.01%)	⬆️
python-3.13	54.60% <31.57%> (+0.01%)	⬆️
python-3.14	54.60% <31.57%> (+0.01%)	⬆️
python-filler-3.12	22.67% <5.26%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/node/node.py	87.11% <78.94%> (+0.22%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.