DM-32 capabilities.json models the CPS ceiling, not the radio's real constraints

[emuehlstein]

Summary

radios/baofeng_dm32/capabilities.json currently models the CPS ceiling, not the radio:

"limits": { "max_channels": 4000, "max_zones": 250, "max_channels_per_zone": 250 }

Those are the numbers the CPS will accept. They are not the numbers that produce a
working codeplug. Every DM-32UV constraint that has actually cost us debugging time
is currently unmodeled, so a profile can validate clean and still generate a plug that
is silently broken on hardware.

This issue proposes extending the capabilities file (and the validator that reads it)
with the constraints below. All of them are field-verified or read directly out of
NeonPlug's DM-32UV codec — sources cited per item.

Proposed constraint block

Illustrative shape, not a final schema — naming/nesting is up for discussion:

{
  "id": "baofeng_dm32",
  "name": "Baofeng DM-32",
  "limits": {
    "max_channels": 4000,
    "max_zones": 250,
    "max_channels_per_zone": 250,

    "max_scanlists": 250,
    "max_scanlist_members": 15,
    "max_zone_name_chars": 16,
    "max_channel_name_chars": 16,
    "max_scanlist_name_chars": 10,
    "max_contact_name_chars": 16
  }
}

The constraints, and why each one matters

1. max_scanlist_members: 15 — highest value, hardest won

The on-radio scanlist record stores its channel list at +0x1A, and the next field
begins at +0x38. That is 30 bytes = 15 x uint16. NeonPlug's own codec agrees:
its comment reads "30 bytes, uint16 array LE, 0x0000 terminated, max 15 channels",
channelCount at +0x0B is documented 0-15, and both encoder and decoder hard-loop
i < 15.

Source: src/radios/dm32uv/structures.ts

Worth stating explicitly because it is a real point of confusion: the OEM CPS shows
16 entries. It adds a "Current Channel" entry at index 0 on top of your 15 defined
members. So a "16" in vendor-facing documentation is not wrong, it is describing the
UI. Storage is 15. A generator must target 15.

Failure mode when exceeded: not a rejected import. On a real plug, an oversized list
made every scanlist unselectable on the radio, not just the offending one.

2. The full-15 edge case (document, do not silently rely on)

NeonPlug clamps writes to Math.min(len, 15), but only emits the 0x0000 terminator
if (channelCount < 15). At exactly 15 the 30-byte field is full and no
terminator is written, so the radio's parse can run past the end of the record into
the adjacent field.

This is the suspected mechanism behind the all-scanlists-unselectable failure above.
It is not yet verified on hardware. Recommendation: treat 15 as the hard cap for
validation, but consider a warning at exactly 15, and note in radios/README that
dropping the largest list to 14 is the first diagnostic if scan selection misbehaves.

3. channelCount must equal the exact member count — never +1

A separate, already-fixed defect in our own generator: writing channelCount = len + 1
(a "1-based" misreading) causes the radio to read one entry past a correctly sized
array. Same class of bug as #2, different cause. Any exporter writing this field needs
a test asserting channelCount == len(members).

4. Name length limits

• Channel name: 16 chars
• Zone name: 16 chars
• Scanlist name: 10 chars — NeonPlug encodes it as 11 bytes null-terminated,
  name.slice(0, 10), so an 11th character is silently truncated, not rejected.
• Contact name: 16 chars

The scanlist case matters most for a generator: truncation is silent, and two
scanlists whose names differ only after character 10 collide into the same on-radio
name. Since profiles reference things by stable ID this will not corrupt selection,
but it will produce a confusing radio UI.

Suggested validator behavior

profile.py already reads limits and raises ProfileValidationError for zones and
channels. The same pattern extends naturally:

• Hard error: any constraint exceeded (> max_scanlist_members, name over limit).
• Warning: scanlist at exactly 15 (see Add normalized codeplug model #2), until hardware-verified.
• Error messages should keep the existing style, which is good — state the observed
  value, the limit, and the offending entity name.

Scope note

Profile 0.1 deliberately excludes scanlists and contacts, so items #1-#3 are not
enforceable end-to-end yet. Filing now anyway because:

1. The name limits (Generate NeonPlug exports from ResolvedCodeplug #4) apply to 0.1 today — channels and zones are already
   generated, and max_*_name_chars is enforceable immediately.
2. Scanlists are exactly where the DM32 pain was concentrated, so it is worth having
   these constraints written down before 0.2 designs around them, rather than
   rediscovering them on hardware.

Happy to open a PR with the capabilities block and validator changes if the shape
above looks right.

[emuehlstein]

Firmware-varying limits: a limit may not be a single value

Adding a related case to this issue, since it lands on the same premise —
capabilities.json describing something other than what the radio will actually
accept. This one goes a layer deeper than wrong values: for the DM-32, at
least one limit is not a constant, because it changes with the installed
firmware.

The case

Contact storage on the DM-32UV varies by firmware:

Firmware	Record function	CSV contacts
DM32.01.L01.048	removed	150,000
DM32.01.01.049	restored	50,000

Baofeng traded the record function for contact memory in 048, then reverted in
049. So max_contacts is 150000 or 50000 depending on the image, and the
upgrade direction is the shrinking one — a codeplug that fits a 048 radio can
overflow the same radio after a routine firmware update.

Current state

No firmware concept exists in the repo. grep -rniE 'firmware|048|049' across
src/ radios/ schemas/ docs/ tests/ returns nothing. Capabilities are modeled
strictly per radio model.

max_contacts is declared in capabilities-0.2.schema.json but is absent from
both shipped capabilities.json files, and nothing reads it. Enforcement today
is only:

src/codeplugger/profile.py:245   max_zones
src/codeplugger/profile.py:276   max_channels_per_zone
src/codeplugger/profile.py:283   max_channels

plus _check_name_length for max_zone_name_chars / max_channel_name_chars.
So max_contacts is currently inert even if populated — which is consistent
with the "partial enforcement" point already in this issue.

Why this is the same bug as #3

This issue's framing is that the numbers describe the CPS ceiling rather than a
working codeplug. Firmware-varying limits are that same failure one level down:
even a correct single number is wrong for some radios of the same model,
because the constraint is a function of (model, firmware), not model alone.
Committing max_contacts: 150000 would be exactly as misleading as the current
max_channels_per_zone: 250 — right for some radios, silently wrong for others.

Suggested direction

Firmware-qualified limits: a base limits block plus overrides keyed on
firmware prefix, with the generator resolving against the firmware actually
installed on the target radio.

{
  "limits": { "max_contacts": 50000 },
  "firmware_overrides": [
    { "match": "DM32.01.L01.048", "limits": { "max_contacts": 150000 } }
  ]
}

This needs an input the generator does not have today: which firmware is on the
physical radio. That is what #8 proposes recording, keyed on radio_instance
(which resolved.py already threads through to
ResolvedCodeplug.radio_instance_id). So the two are coupled — firmware-aware
limits are not really implementable until instance metadata exists, and
hardware_family / firmware want to live in the same place for the
soft-brick-safety reasons noted there.

Conservative fallback if that is too much machinery: omit max_contacts
rather than commit a wrong constant. The schema already documents "Omit when
unknown," and an omitted limit skips its check by design. Better than encoding
a number that is wrong for half the fleet.

Out of scope, deliberately

The record function also varies across those same two firmwares, but it is
not a codeplug constraint — it consumes no codeplug space and changes no
channel byte. By this repo's boundary rule that is reference material
(Chicago-Offline/dm32-info → FIRMWARE.md, where the version table already
records it), not a generator concern. It would only become one if a profile
mapped a button to the record function, and profile 0.1 has no button
mappings.

Flagging it explicitly so the distinction does not get lost: storage limits
that vary by firmware belong in capabilities; feature availability that varies
by firmware does not.

[emuehlstein]

Status update:

• A large portion of this issue is already addressed by merged capability-limit work (PR Enforce declared capability limits; add name-length limits #7).
• Remaining firmware-varying-limit concerns are now better unblocked by the instance-registry path in PR Add optional radio instance registry validation #11.

Recommendation: keep this issue open for the firmware-qualified limit follow-up and close once that remaining scope lands.

[emuehlstein]

Status update:

• A large portion of this issue is already addressed by merged capability-limit work (PR Enforce declared capability limits; add name-length limits #7).
• Remaining firmware-varying-limit concerns are now better unblocked by the instance-registry path in PR Add optional radio instance registry validation #11.

Recommendation: keep this issue open for the firmware-qualified limit follow-up and close once that remaining scope lands.

[emuehlstein]

Closing — implemented, with two corrections worth recording.

radios/baofeng_dm32/capabilities.json is now capabilities_version: 0.2 and carries the proposed constraints (landed in ed5628b):

"max_channels": 4000, "max_zones": 250, "max_channels_per_zone": 64,
"max_scan_lists": 32, "max_channels_per_scan_list": 15,
"max_rx_group_lists": 32, "max_talkgroups_per_rx_group_list": 32,
"max_channel_name_chars": 16, "max_zone_name_chars": 16,
"max_scan_list_name_chars": 10, "max_contact_name_chars": 16,
"max_contacts": 50000

Correction 1 — max_channels_per_zone is 64, not 250. The block proposed in this issue kept 250, which is the max_zones count misread as a per-zone channel cap. Confirmed 64 in OEM CPS v1.59 (channels 1-64 per zone). Adopting the proposal verbatim would have re-enshrined the wrong value.

Correction 2 — the item-2 full-15 edge case was wrong and is being retracted in #16. This issue recommended treating exactly-15 as suspect and dropping the largest list to 14 as a diagnostic. Hardware verification on 2026-08-07 (DP570UV) showed the terminator theory is not the mechanism: the 57-byte record buffer is fill(0x00) and +0x38 padding already terminates a full list, so that guard was never load-bearing. Lists at exactly 15 are fine and are in active use (AirBand, FAMILY, HAM, MARINE). The real cause is that +0x0F is not a member slot — OEM CPS moves the first grid member there on write, that channel is neither scanned nor displayed, and CPS counts it. That is also the actual reason the CPS shows 16, superseding the Current Channel explanation.

Beyond the original scope: a firmware_limits mechanism this issue did not contemplate. DM32.01.L01.048 → 150,000 contacts, DM32.01.01.049 → 50,000, with base max_contacts pinned to the smaller value so validating without a known firmware cannot pass a profile that only fits on 048. That encodes the 048→049 capacity regression as a validation rule.

Enforcement status — deliberately partial, and that is correct:

• Live: max_zones, max_channels_per_zone, max_channels (profile.py:355-397), max_zone_name_chars (profile.py:368), max_channel_name_chars (resolved.py:222 — deferred to resolve time because no channel name exists before then).
• Declared but inert: every scan-list / RX-group / contact limit. profile-0.1.schema.json exposes only ['id','name','radio','radio_instance','version','zones'], so there is nothing to check them against yet. _check_name_length skips absent capabilities by design, so an incomplete capabilities file degrades to prior behavior instead of failing falsely.

Items 1-3 of this issue therefore remain unenforceable end-to-end until profile 0.2 introduces scan lists and contacts. That is 0.2 scope (see #8, whose instance_registry_path is already threaded through resolved.py), not remaining work here. 30 tests pass.