NDStateMachine modules never populate diff or logs in module output despite documenting them #530

Summary

Every NDStateMachine-backed (Gen-3) module returns diff: [] and — at output_level: debug — logs: [], unconditionally. Neither key is ever populated, yet 24 modules document diff as returned: always with a populated sample, and 19 document logs. Surfaced by review of #403 (thread #403 (comment)), but it is a framework gap, not a module one.

Root cause

• NDStateMachine only ever calls self.output.assign(after=..., before=..., proposed=...) (nd_state_machine.py:85) and later assign(after=...). It never passes diff or logs.
• NDOutput.format() computes changed by comparing before and after (get_diff_collection) but does not derive a diff from the same comparison; it emits self._diff, which stays at its [] default.
• Nothing in module_utils collects log records into a list: common/log.py only permits file handlers, so NDOutput._logs has no producer.
• diff= has never been assigned since the initial ND 4.2 state-machine commit (git log -S"diff=" on nd_state_machine.py).

The only diff that exists today is API-level: Results stores a per-call diff that format_with_verbosity() surfaces as api_diff at -vvv. That is the payload sent, not a before/after config diff.

Scope

25 modules construct NDStateMachine (the nd_interface_* family, nd_manage_fabric_*, nd_local_user, nd_maintenance_mode, nd_manage_vpc_pair, nd_manage_policy_group, ...). Five of them do not document diff at all; the rest promise it.

Related

• ND module's result output mismatch #304 — output-consistency discussion. The resource-manager module populates diff in the cisco.dcnm shape ({merged, deleted, gathered, debugs}), so the collection currently has two conventions: dcnm-style vs. empty. The shape decision belongs to ND module's result output mismatch #304; this issue is about the state-machine layer never producing one at all.
• NDStateMachine failure output misreports changed/after when an API mutation fails mid-run #389 / PR Prototype NDStateMachine final-state reconciliation #525 — the changed/after-on-failure rewrite touches nd_output.py and already gates diff emission on "final state provable". A fix here should land on top of (or inside) that work rather than collide with it.
• Document RETURN output for fabric modules on develop #358 — RETURN documentation audit; whichever shape is chosen, the per-module samples need updating.

Suggested direction

1. Derive diff in NDOutput.format() alongside changed, from before/after using the existing identifier/get_diff_config machinery: one entry per identifier that is new, removed, or changed. Ansible's native shape — a list of {"before": {...}, "after": {...}, "before_header": "<identifier>", "after_header": "<identifier>"} — makes ansible-playbook --diff render it for free; if ND module's result output mismatch #304 settles on the dcnm shape instead, the same comparison feeds that.
2. logs: either attach a small in-memory logging.Handler to the nd logger when output_level == debug and hand its records to assign(logs=...), or remove the key from the documentation. The handler is ~20 lines and delivers what the docs already promise.
3. Unit tests in test_nd_output.py for create / update / delete / no-change diff shapes, and a state-machine test asserting diff is non-empty on a changed merged run.
4. Update the RETURN samples across the affected modules once the shape is fixed (ties into Document RETURN output for fabric modules on develop #358).

Cisco Nexus Dashboard Version

4.2.1 (behavior is controller-independent)