feat(lifecycle): durable host bindings, background reconciliation and safety gates

[berlikm]

Summary

Durable host bindings, background Device/VM reconciliation, and safety gates (#121).

Rebased onto 1.0.5 + #115 + #117 + #110. Depends on #110. Lifecycle-only delta:

https://github.com/berlikm/nbxsync/compare/fix/tag-render-device-context...fix/inherited-host-lifecycle

Highlights

• ZabbixHostBinding — internal sync identity (no UI/API by design)
• allow_inherited_deletion / adopt_existing_hosts default off
• Migration 0016
• 1.0.5 trigger-dependency hook stays after the assignment loop and remains disabled by default

Scope frozen at tip 15a496d.

Merge after: #110
Next: #129

[berlikm]

Commit history note

This PR currently shows 24 commits because it includes stacked commits from dependencies (#115, #113, #123, #124). Once the dependency PRs are merged into development, this branch will be rebased and squash-merged.

The actual durable-binding delta (after dependencies land) consists of ~7 commits:

1. feat(binding): durable ZabbixHostBinding for host identity — the core model + migration
2. fix(binding): reconcile hosts after assignment removal — candidate set union
3. fix(binding): preserve delete job compatibility — legacy instance-arg support
4. fix(binding): preserve legacy host ids on delete — capture unmigrated hostids
5. fix(binding): preserve legacy sync compatibility — getattr defaults
6. fix(exclusion): keep tag rendering contract — don't pass object to render()
7. fix(exclusion): retire delete-mapped hosts — excluded hosts still retire

Full verification on the integration branch (integration/all-prs): 1,128 tests pass, E2E confirmed against Zabbix 7.0.28.

[berlikm]

Conflict resolution note for rebase

When rebasing this PR after #110 and #115 land, there will be two conflicts in nbxsync/utils/sync/hostsync.py:

Conflict 1: host_binding import (line ~14)

• Ours (this PR): adds from nbxsync.utils.host_binding import backfill_or_resolve_conflict, delete_host_binding, delete_host_binding_by_id, get_host_binding, set_host_binding
• Theirs (fix(render): device-context tag/hostgroup rendering and UI previews #110/feat: Site/SiteGroup/Region inheritance, recursive ancestry, exclusion and inherited sync UI #115): no host_binding import

Correct resolution: Take this PR's version (the import is needed for durable bindings).

Conflict 2: tag loop (line ~417)

• Ours (this PR): exclude_tag = getattr(self.pluginsettings, 'exclude_tag', '') + for assigned_tag in self.context.get('all_objects', {}).get('tags'): + value, _ = assigned_tag.render()
• Theirs (feat: Site/SiteGroup/Region inheritance, recursive ancestry, exclusion and inherited sync UI #115 + fix(render): device-context tag/hostgroup rendering and UI previews #110): for assigned_tag in (self.context.get('all_objects', {}).get('tags', []) or []): + value, _ = assigned_tag.render(object=sync_target)

Correct resolution: Combine all three concerns:

exclude_tag = getattr(self.pluginsettings, 'exclude_tag', '')
for assigned_tag in (self.context.get('all_objects', {}).get('tags', []) or []):
    if exclude_tag and assigned_tag.zabbixtag.tag == exclude_tag:
        continue
    value, _ = assigned_tag.render(object=sync_target)

Important: The render(object=sync_target) call from #110 must be preserved. This PR's "keep tag rendering contract" commit reverted it to render(), but that was written before #110 was merged. With both PRs in the integration, render(object=sync_target) is the correct version — it renders Jinja2 tags against the actual device being synced, not the assignment's source object.

Migration

After rebasing, rename 0014_zabbixhostbinding.py to the next available number after the template-rule migrations (#117 → 0014, #119 → 0015). The #117 template-rule migration should depend on this binding migration to keep the chain linear: 0013 → 0014_zabbixhostbinding → 0015_zabbixtemplaterule → 0016_zabbixtemplaterule_hostgroup_tag.

Verified in the integration-test branch: 1135 tests pass, E2E confirmed (create, sync, verify hostgroups/tags, delete, verify Zabbix removal).

[berlikm]

Added commit 2d1cf37 refining deletion semantics after review:

Exclusion is explicit operator intent, so it is no longer gated by allow_inherited_deletion.

Rationale: the safety gate exists for inheritance-driven deletions a device owner cannot foresee (e.g. a Site moved into another SiteGroup silently stripping a server assignment). An exclude_tag assignment is a deliberate operator decision — semantically identical to a statusmapping entry mapped to deleted and to deleting the Device/VM in NetBox, and both of those paths delete unconditionally. Leaving exclusion gated made it the one explicit-intent path that silently stopped deleting.

Scope of the change:

• jobs/synchost.py: exclusion branch deletes unconditionally again; the gate now only covers lost ZabbixServerAssignments (binding retirement) and OOB interface retention.
• Regression test pins allow_inherited_deletion=False + exclusion → host is still deleted. (The pre-existing exclusion tests asserted deletion but passed vacuously: the mocked settings object made the gate attribute truthy.)
• docs/configuration.md + settings.py comments updated to describe the narrowed gate scope.

Net effect with default settings: exclude tag, deleted status mapping, and NetBox object deletion always remove the Zabbix host; only assignment loss stays log-only until allow_inherited_deletion is enabled.

[berlikm]

Added nested hostgroup support (commits 57b29a2 + 7fe6da3): parent-first group creation.

Problem: Zabbix nesting is a name convention. Creating A/B/C never auto-creates A/A/B — the parents stay phantom groups that cannot hold hosts or permissions. Since Zabbix only inherits user-group permissions and tag filters into a subgroup when its parent already exists, leaf-first creation silently breaks permission-based dashboard/access designs (verified live on Zabbix 7.0.28).

Fix: ensure_parent_hostgroups() materializes missing path segments in parent-first order before creating the leaf. Idempotent (exact-name hostgroup.get first, create only if missing) and wired into both creation paths: HostGroupSync.try_create() and the on-demand creation in HostSync.get_groups(). Malformed names (empty segments, leading/trailing slashes) are intentionally skipped so Zabbix's own API validation error surfaces for the leaf instead of being masked.

Tests: 4 new cases (creation order, idempotency, flat names untouched, malformed passthrough); nbxsync.tests.utils.test_hostgroupsync green — 13/13 on NetBox 4.5.10 / Zabbix 7.0.

[berlikm]

Restacked onto the 1.0.5 rebase of #110.

Lifecycle-only: ZabbixHostBinding, background reconciliation, allow_inherited_deletion / adopt_existing_hosts default off, migration 0016.

Trigger dependencies: 1.0.5's hook is preserved through the bindings rewrite. It still defaults to disabled, and it still runs once after the assignment loop (and after unassigned-binding retirement) — not inside the per-assignment loop, and not on excluded / VM / DELETED paths. Enabling it remains an operator choice, not something this stack turns on.

Scope frozen at e0e5466. Merge after #110; next is #129.