WIP: profile phonebook write contracts

[MarcLeinenDE]

Adds a hard-gated physical research profiler for the next complete-SDK-coverage block.

Scope of the profiler:

• synthetic local phonebook group create/update/delete
• synthetic local contact create/update/delete
• isolated update_pb candidate matrix with polling and semantic classification
• bounded candidate matrix for move_contacts_to_group
• read-back verification after every operation

Physical evidence — first run:

• initial groups=1, local contacts=0
• addnew_group result=0 + readback success
• update_group result=0 + readback success
• second group create result=0 + readback success
• addnew_pb result=0 + readback success
• first update_pb returned result=0 but expected name change was not visible
• failure-path cleanup removed the known synthetic contact and both groups

Physical evidence — hardened second run:

• initial groups=1, local contacts=0
• group create/update/create all succeeded with readback
• nested update_pb candidates (STRINGS_FULL, INT_IDS_FULL, STRINGS_MINIMAL) returned result=0 on the same index
• target mobile value was applied
• target name and target email were not observed
• no copy-on-update row was observed
• flat update_pb payload returned result=-5
• move_contacts_to_group confirmed with newgroup as a string and contacts as a single string contact index; result=0 and both group-specific/local readbacks confirmed the move

Important profiler defect found by the second run:

• final group count returned to baseline
• final local contact count was 5 instead of initial 0
• the profiler nevertheless printed PASS because cleanup/final success relied on synthetic name prefixes; update/move behavior can make name-prefix cleanup insufficient
• the five new contact indexes from the run are 3,4,5,6,7

Required harness correction before another lifecycle run:

• track pre-run local index set and treat every new index as synthetic regardless of name field
• cleanup all new indexes, not just prefix matches
• require exact final index-set/cardinality restoration before PASS
• field-specific update_pb follow-up must change each field independently to resolve actual firmware behavior

Safety/privacy:

• requires NR2301_WRITE_INTEGRATION=1
• synthetic local contacts/groups only
• no SIM contacts
• no USB management-mode mutation

WIP until residue from the second run is explicitly cleaned, the profiler harness is corrected, and the remaining update_pb field semantics are resolved.

2026-09-21 continuation:

• added examples/check_cleanup_phonebook_residue.py for the known second-run residue
• cleanup is inventory-first and prints only indexes/boolean synthetic markers, not contact data
• automatic deletion is hard-gated by NR2301_PHONEBOOK_RESIDUE_CLEANUP=1
• it will only delete when every current local row is on known residue index 3..7 and each row still carries at least one exact synthetic marker
• any unexpected/local row makes the helper refuse all automatic cleanup
• regression test added for the cleanup guard
• current profiler already tracks pre-run index sets and requires exact final restoration, so a new write run is blocked until residue cleanup succeeds

Superseded contract-development status

As of 2026-09-21, this old research PR must not be used as the canonical source for Phonebook SDK contracts.

Canonical order remains:

1. nr2301-api/main is the authoritative contract/evidence baseline.
2. The SDK is implemented only after that API contract is normalized.
3. Physical SDK validation then confirms the implementation against the API baseline.

Phonebook contract work from this PR has since been superseded by later API evidence, including:

• normalized write lifecycle semantics,
• shipped-WebUI UniEncode/UniDecode contact text codec,
• corrected update_pb field behavior,
• confirmed comma-separated plural move/delete contracts.

Those normalized contracts are already reflected in current nr2301-python/main.

Remaining purpose of this PR/branch:

• safely inventory and remove synthetic local-phonebook residue left by the historical profiler run;
• retain research history only.

Do not run the old plaintext update profilers to derive or change SDK behavior. Any genuinely new physical finding must first be recorded/normalized in nr2301-api, then propagated to the SDK.