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

Adds a client-side guard to stop crashes when calling save(allow_upsert=True) on nodes whose HFID includes a CoreNumberPool-sourced attribute; it now raises a clear ValidationError before any request. Addresses IHS-119.

• Bug Fixes
  • Added a guard in async and sync InfrahubNode.save() to block upsert when an HFID component is an unresolved pool-backed attribute (either a from_pool dict with no value or a pool node object); raises ValidationError early.
  • Upsert still works when an id is set or when the pool-backed attribute is not part of the HFID.
  • Added is_unresolved_pool_attribute() for attributes; expanded tests; updated the Resource Manager guide with warning and alternatives and the SDK reference; added a changelog entry.

^{Written for commit da072d3. Summary will update on new commits. Review in cubic}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	da072d3
Status:	✅  Deploy successful!
Preview URL:	https://41292ab9.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 81.81818% 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.58%   +0.01%     
==========================================
  Files         134      134              
  Lines       11442    11490      +48     
  Branches     1730     1742      +12     
==========================================
+ Hits         9333     9374      +41     
- Misses       1564     1570       +6     
- Partials      545      546       +1     

Flag	Coverage Δ
integration-tests	41.79% <59.09%> (+0.29%)	⬆️
python-3.10	54.61% <36.36%> (+0.02%)	⬆️
python-3.11	54.59% <36.36%> (+<0.01%)	⬆️
python-3.12	54.59% <36.36%> (+0.02%)	⬆️
python-3.13	54.59% <36.36%> (+<0.01%)	⬆️
python-3.14	54.61% <36.36%> (+0.02%)	⬆️
python-filler-3.12	22.63% <9.09%> (-0.08%)	⬇️

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

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

... and 15 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[ogenstad]

I'm wondering if we should forbid this all together if the attribute can come from a pool. It could be that we should have

if attr.value is not None and attr.is_from_pool_attribute():

I.e. that this would be problematic for upsert mutations if a value hadn't been assigned from a pool already. Was that something that you considered?

[cubic-dev-ai]

1 issue found across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[ogenstad]

Looks good overall, but as we're testing with mocked data it could be nice either have an integration test or at least validate against a real server.

[ogenstad]

The bug report specifically mentions Node.save() as a problem area but I think we can have a similar situation in Node.create(). One additional comment here is that the code looks exactly the same for the sync and async version, with that in mind I think we can create a helper method that can be called from both of these to ensure that we keep the code in sync in the future.