feat: add priority-aware talkgroup policy

Author: arancormonk

docs/cli.md

@@ -187,7 +187,7 @@ Notes
 - Enable trunking (NXDN/P25/EDACS/DMR): `-T`
 - Conventional scan mode: `-Y` (not trunking; scans for sync on enabled decoders)
 - Channel map CSV: `-C <file>` (e.g., `connect_plus_chan.csv`)
-- Group list CSV (allow/block + labels): `-G <file>`
+- Group list CSV (allow/block + labels, optional `priority/preempt/audio/record/stream` policy columns): `-G <file>`
 - CSV formats and examples: `docs/csv-formats.md` and `examples/`
 - Use group list as allow/whitelist: `-W`
 - Tune controls: `-E` disable group calls, `-p` disable private calls, `-e` enable data calls, `--enc-lockout` do not tune encrypted P25 calls, `--enc-follow` allow encrypted (default)
@@ -202,6 +202,9 @@ Notes
   - Env (DMR): Hangtime and grant timeout overrides:
     - `DSD_NEO_DMR_HANGTIME=<seconds>` — post‑voice hangtime before returning to CC
     - `DSD_NEO_DMR_GRANT_TIMEOUT=<seconds>` — max seconds waiting for voice after grant
+  - Env (priority preemption):
+    - `DSD_NEO_TG_PREEMPT_MIN_DWELL_MS=<ms>` — minimum active call dwell before displacement (default `750`)
+    - `DSD_NEO_TG_PREEMPT_COOLDOWN_MS=<ms>` — cooldown between displacement attempts (default `1000`)
 
 ## RTL‑SDR details (`-i rtl` / `-i rtltcp`)
 

docs/csv-formats.md

@@ -50,11 +50,33 @@ Required columns:
 
 Notes:
 
-- Only the first 3 columns are used; extra columns are ignored.
+- The first line is treated as header text and is required.
+- Legacy/default behavior uses only the first 3 columns; extra columns are ignored.
 - `mode` is matched literally by features that consult it:
   - `A` usually means allow/normal.
-  - `B` and `DE` are treated as locked out in the UI helpers.
-- Names are not CSV-escaped; avoid commas in `name`.
+  - `B` and `DE` are treated as locked out.
+- Names are not CSV-escaped; avoid commas and line breaks in fields.
+
+Extended policy columns are supported only when the header opts into this exact ordered prefix starting at column 4:
+
+1. `priority` (0..100, default `0`)
+2. `preempt` (`true`/`false`, default `false`)
+3. `audio` (`on`/`off`, default from `mode`)
+4. `record` (`on`/`off`, default from `mode`)
+5. `stream` (`on`/`off`, default from `mode`)
+6. `tags` (free text metadata)
+
+Important behavior:
+
+- The header must contain `priority` in column 4 and continue in that order for the available policy columns.
+- If the header is legacy/unknown (for example `id,mode,name,metadata`), optional policy parsing is disabled and extra
+  columns remain legacy metadata.
+- `id` supports exact IDs (`1201`) and ranges (`1200-1299`).
+  - Exact rows populate both runtime alias display state and policy.
+  - Range rows are policy-only and are not inserted as exact aliases.
+- Exact duplicates preserve first-match behavior.
+- `audio=off` forces `record=off` and `stream=off`.
+- `mode=B`/`DE` forces media fields off regardless of optional values.
 
 Example:
 
@@ -64,6 +86,15 @@ DEC,Mode(A=Allow; B=Block; DE=Enc),Name,Tag
 22033,DE,Law Dispatch,Law
 ```
 
+Extended policy example:
+
+```csv
+id,mode,name,priority,preempt,audio,record,stream,tags
+1201,A,Dispatch 1,80,true,on,on,on,primary
+1202,A,Dispatch 2,40,false,on,off,on,secondary
+1300-1399,A,Ops Range,10,false,on,on,on,wide
+```
+
 ## Decimal Key List CSV (`-k <file>`)
 
 Purpose: Import decimal key IDs and values for basic privacy/scrambler helpers.

docs/ui-terminal.md

@@ -25,6 +25,11 @@ Common controls:
 - Back / close: `Esc`, `q`, `Left`
 - Item help: `h`
 
+Group policy reload:
+
+- In the Trunking/Import menu path, importing a group list (`-G` CSV) performs a full policy reload. On parse failure,
+  the currently loaded list remains active.
+
 ## Hotkeys (Main Screen)
 
 Keys are case-sensitive. Some commands only make sense in specific modes (for example, trunking controls require

include/dsd-neo/core/csv_import.h

@@ -20,6 +20,7 @@ extern "C" {
 #endif
 
 int csvGroupImport(dsd_opts* opts, dsd_state* state);
+int csvGroupImportPath(const char* group_file_path, dsd_state* state);
 int csvLCNImport(dsd_opts* opts, dsd_state* state);
 int csvChanImport(dsd_opts* opts, dsd_state* state);
 int csvKeyImportDec(dsd_opts* opts, dsd_state* state);

include/dsd-neo/core/state_ext.h

@@ -45,6 +45,13 @@ enum { DSD_STATE_EXT_MAX = 32 };
 typedef enum dsd_state_ext_id {
     DSD_STATE_EXT_ENGINE_START_MS = 0,
     DSD_STATE_EXT_ENGINE_TRUNK_CC_CANDIDATES = 1,
+    /*
+     * DSD_STATE_EXT_CORE_TG_POLICY lives in the engine range (0-7) because it
+     * is a cross-cutting core facility, not module-private state. Engine owns
+     * 0-1; this slot is a documented exception, not a precedent for arbitrary
+     * core use.
+     */
+    DSD_STATE_EXT_CORE_TG_POLICY = 2,
     DSD_STATE_EXT_PROTO_NXDN_TRUNK_DIAG = 24,
 } dsd_state_ext_id;
 
@@ -54,6 +61,8 @@ typedef void (*dsd_state_ext_cleanup_fn)(void*);
 
 void* dsd_state_ext_get(dsd_state* state, dsd_state_ext_id id);
 
+const void* dsd_state_ext_get_const(const dsd_state* state, dsd_state_ext_id id);
+
 int dsd_state_ext_set(dsd_state* state, dsd_state_ext_id id, void* ptr, dsd_state_ext_cleanup_fn cleanup);
 
 void dsd_state_ext_free_all(dsd_state* state);

include/dsd-neo/core/talkgroup_policy.h

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/*
+ * Copyright (C) 2026 by arancormonk <180709949+arancormonk@users.noreply.github.com>
+ */
+
+/**
+ * @file
+ * @brief Talkgroup/private policy evaluation and shared mutation helpers.
+ */
+
+#pragma once
+
+#include <dsd-neo/core/opts_fwd.h>
+#include <dsd-neo/core/state_fwd.h>
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    DSD_TG_POLICY_MATCH_NONE = 0,
+    DSD_TG_POLICY_MATCH_RANGE = 1,
+    DSD_TG_POLICY_MATCH_EXACT = 2,
+} dsd_tg_policy_match_type;
+
+typedef enum {
+    DSD_TG_POLICY_PRIVATE_ALLOWLIST_UNKNOWN_ALLOW = 0,
+    DSD_TG_POLICY_PRIVATE_ALLOWLIST_UNKNOWN_BLOCK = 1,
+} dsd_tg_policy_private_allowlist_mode;
+
+typedef enum {
+    DSD_TG_POLICY_HOLD_COMPAT_GRANT = 0,
+    DSD_TG_POLICY_HOLD_FORCE_MEDIA_ONLY = 1,
+    DSD_TG_POLICY_HOLD_FORCE_TUNE_AND_MEDIA = 2,
+} dsd_tg_policy_hold_behavior;
+
+typedef enum {
+    DSD_TG_POLICY_SOURCE_IMPORTED = 0,
+    DSD_TG_POLICY_SOURCE_RUNTIME_ALIAS = 1,
+    DSD_TG_POLICY_SOURCE_USER_LOCKOUT = 2,
+    DSD_TG_POLICY_SOURCE_ENC_LOCKOUT = 3,
+    DSD_TG_POLICY_SOURCE_LEGACY_UNKNOWN = 4,
+} dsd_tg_policy_entry_source;
+
+typedef enum {
+    DSD_TG_POLICY_UPSERT_ADD_IF_MISSING = 0,
+    DSD_TG_POLICY_UPSERT_REPLACE_FIRST = 1,
+    DSD_TG_POLICY_UPSERT_REPLACE_LEARNED_ONLY = 2,
+} dsd_tg_policy_upsert_mode;
+
+typedef enum {
+    DSD_TG_POLICY_BLOCK_NONE = 0u,
+    DSD_TG_POLICY_BLOCK_GROUP_DISABLED = 1u << 0,
+    DSD_TG_POLICY_BLOCK_PRIVATE_DISABLED = 1u << 1,
+    DSD_TG_POLICY_BLOCK_DATA_DISABLED = 1u << 2,
+    DSD_TG_POLICY_BLOCK_ENCRYPTED_DISABLED = 1u << 3,
+    DSD_TG_POLICY_BLOCK_ALLOWLIST = 1u << 4,
+    DSD_TG_POLICY_BLOCK_MODE = 1u << 5,
+    DSD_TG_POLICY_BLOCK_HOLD = 1u << 6,
+    DSD_TG_POLICY_BLOCK_AUDIO = 1u << 7,
+    DSD_TG_POLICY_BLOCK_RECORD = 1u << 8,
+    DSD_TG_POLICY_BLOCK_STREAM = 1u << 9,
+} dsd_tg_policy_block_reason;
+
+typedef struct {
+    uint32_t id_start;
+    uint32_t id_end;
+    char mode[8];
+    char name[50];
+    int priority;
+    uint8_t preempt;
+    uint8_t audio;
+    uint8_t record;
+    uint8_t stream;
+    uint8_t is_range;
+    uint8_t source;
+    unsigned int row;
+} dsd_tg_policy_entry;
+
+typedef struct {
+    dsd_tg_policy_match_type match;
+    dsd_tg_policy_entry entry;
+} dsd_tg_policy_lookup;
+
+typedef struct {
+    uint32_t target_id;
+    uint32_t source_id;
+    int encrypted;
+    int data_call;
+    int tune_allowed;
+    int audio_allowed;
+    int record_allowed;
+    int stream_allowed;
+    int priority;
+    int preempt_requested;
+    uint32_t block_reasons;
+    int tg_hold_active;
+    int tg_hold_match;
+    char mode[8];
+    char name[50];
+    dsd_tg_policy_match_type match;
+} dsd_tg_policy_decision;
+
+typedef struct {
+    uint32_t target_id;
+    uint32_t source_id;
+    long freq_hz;
+    int channel;
+    int slot;
+    int requires_tuner_retune;
+} dsd_tg_policy_call_route;
+
+int dsd_tg_policy_make_legacy_exact_entry(uint32_t id, const char* mode, const char* name,
+                                          dsd_tg_policy_entry_source source, dsd_tg_policy_entry* out);
+int dsd_tg_policy_add_range_entry(dsd_state* state, const dsd_tg_policy_entry* entry);
+int dsd_tg_policy_lookup_id(const dsd_state* state, uint32_t id, dsd_tg_policy_lookup* out);
+int dsd_tg_policy_evaluate_group_call(const dsd_opts* opts, const dsd_state* state, uint32_t tg, uint32_t src,
+                                      int encrypted, int data_call, dsd_tg_policy_hold_behavior hold_behavior,
+                                      dsd_tg_policy_decision* out);
+int dsd_tg_policy_evaluate_private_call(const dsd_opts* opts, const dsd_state* state, uint32_t src, uint32_t dst,
+                                        int encrypted, int data_call,
+                                        dsd_tg_policy_private_allowlist_mode allowlist_mode,
+                                        dsd_tg_policy_hold_behavior hold_behavior, dsd_tg_policy_decision* out);
+int dsd_tg_policy_append_legacy_exact(dsd_state* state, const dsd_tg_policy_entry* entry);
+int dsd_tg_policy_upsert_legacy_exact(dsd_state* state, const dsd_tg_policy_entry* entry,
+                                      dsd_tg_policy_upsert_mode mode);
+int dsd_tg_policy_append_group_file_row(const dsd_opts* opts, const dsd_tg_policy_entry* entry,
+                                        const char* legacy_metadata);
+
+int dsd_tg_policy_should_preempt(const dsd_opts* opts, const dsd_state* state,
+                                 const dsd_tg_policy_call_route* candidate_route,
+                                 const dsd_tg_policy_decision* candidate, double now_mono_s);
+int dsd_tg_policy_note_active_call(dsd_state* state, const dsd_tg_policy_call_route* route,
+                                   const dsd_tg_policy_decision* decision, double now_mono_s);
+int dsd_tg_policy_clear_active_call(dsd_state* state, int slot);
+int dsd_tg_policy_clear_active_call_route(dsd_state* state, const dsd_tg_policy_call_route* route);
+
+int dsd_tg_policy_reload_group_file(dsd_opts* opts, dsd_state* state);
+
+#ifdef __cplusplus
+}
+#endif

src/core/CMakeLists.txt

@@ -20,6 +20,7 @@ target_sources(dsd-neo_core PRIVATE
   util/dsd_events.c
   util/dsd_alias.c
   util/dsd_reset.c
+  util/talkgroup_policy.c
   util/synctype.c
   file/dsd_file.c
   file/dsd_import.c

src/core/audio/dsd_audio2.c

@@ -25,7 +25,6 @@
 #include <mbelib.h>
 #include <sndfile.h>
 #include <stdint.h>
-#include <stdio.h>
 #include <string.h>
 #include <sys/types.h>
 
@@ -1327,57 +1326,9 @@ playSynthesizedVoiceSS4(dsd_opts* opts, dsd_state* state) {
         encR = 1;
     }
 
-    //WIP: Mute if on B list (or not W list)
-    char modeL[8];
-    sprintf(modeL, "%s", "");
-    char modeR[8];
-    sprintf(modeR, "%s", "");
-
     unsigned long TGL = (unsigned long)state->lasttg;
     unsigned long TGR = (unsigned long)state->lasttgR;
-
-    //if we are using allow/whitelist mode, then write 'B' to mode for block
-    //comparison below will look for an 'A' to write to mode if it is allowed
-    if (opts->trunk_use_allow_list == 1) {
-        sprintf(modeL, "%s", "B");
-        sprintf(modeR, "%s", "B");
-    }
-
-    for (unsigned int gi = 0; gi < state->group_tally; gi++) {
-        if (state->group_array[gi].groupNumber == TGL) {
-            strncpy(modeL, state->group_array[gi].groupMode, sizeof(modeL) - 1);
-            modeL[sizeof(modeL) - 1] = '\0';
-            // break; //need to keep going to check other potential slot group
-        }
-        if (state->group_array[gi].groupNumber == TGR) {
-            strncpy(modeR, state->group_array[gi].groupMode, sizeof(modeR) - 1);
-            modeR[sizeof(modeR) - 1] = '\0';
-            // break; //need to keep going to check other potential slot group
-        }
-    }
-
-    //flag either left or right as 'enc' to mute if B
-    if (strcmp(modeL, "B") == 0) {
-        encL = 1;
-    }
-    if (strcmp(modeR, "B") == 0) {
-        encR = 1;
-    }
-
-    //if TG Hold in place, mute anything but that TG #132
-    if (state->tg_hold != 0 && state->tg_hold != (uint32_t)TGL) {
-        encL = 1;
-    }
-    if (state->tg_hold != 0 && state->tg_hold != (uint32_t)TGR) {
-        encR = 1;
-    }
-    //likewise, override and unmute if TG hold matches TG
-    if (state->tg_hold != 0 && state->tg_hold == (uint32_t)TGL) {
-        encL = 0;
-    }
-    if (state->tg_hold != 0 && state->tg_hold == (uint32_t)TGR) {
-        encR = 0;
-    }
+    (void)dsd_audio_group_gate_dual(opts, state, TGL, TGR, encL, encR, &encL, &encR);
 
     //test hpf
     if (opts->use_hpf_d == 1) {