feat: implement ext-id.unique for tep-1018

ref #141

Signed-off-by: 35V LG84 <35vlg84-x4e6b92@e257.fi>

Author: 35VLG84

docs/tep/tep-1018.adoc

@@ -55,15 +55,15 @@ See also future plans for use case xref:use-case-lookup[lookup].
 
 Changes to conf-settings
 
-* [ ] new configuration table `kernel.ext-id`
-** [ ] option to enforce uniqueness `kernel.ext-id.unique = <true | false>`
+* [x] new configuration table `kernel.ext-id`
+** [x] option to enforce uniqueness `kernel.ext-id.unique = <true | false>`
 ** [ ] _future_: option to enforce existence of `ext-id` `kernel.ext-id.mandatory = <true | false>`
 
 ==== Tackler `init` / `new` commands
 
 Changes to tackler `new` or `init` commands
 
-* [ ] Add the ext-id section, with `unique = false`
+* [x] Add the ext-id section, with `unique = false`
 
 
 === Filtering Changes
@@ -86,8 +86,6 @@ Changes to filtering logic or implementation
 
 Changes to the tackler core engine (e.g. core implementation)
 
-* [ ] item
-
 
 ==== API Changes
 

tackler-cli/src/commands/init/tackler_toml.rs

@@ -1,5 +1,5 @@
 /*
- * Tackler-NG 2025
+ * Tackler-NG 2025-2026
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -15,6 +15,7 @@ pub(super) const TXT: &str = r#"#
 ###   Valid values are <true|false>
 strict = false
 audit = { mode = false, hash = "SHA-256" }
+ext-id = { unique = false }
 timestamp = { default-time = 00:00:00, timezone = { name = "UTC" } }
 
 [kernel.input]

tackler-core/src/config/items.rs

@@ -4,8 +4,8 @@
  */
 use crate::config::raw_items::{
     AccountsPathRaw, AccountsRaw, AuditRaw, BalanceGroupRaw, BalanceRaw, CommoditiesPathRaw,
-    CommoditiesRaw, ConfigRaw, EquityRaw, ExportRaw, FsRaw, GitRaw, InputRaw, KernelRaw, PriceRaw,
-    RegisterRaw, ReportRaw, ScaleRaw, TagsPathRaw, TagsRaw, TimestampRaw, TimezoneRaw,
+    CommoditiesRaw, ConfigRaw, EquityRaw, ExportRaw, ExtIdRaw, FsRaw, GitRaw, InputRaw, KernelRaw,
+    PriceRaw, RegisterRaw, ReportRaw, ScaleRaw, TagsPathRaw, TagsRaw, TimestampRaw, TimezoneRaw,
     TransactionRaw,
 };
 use crate::config::{to_export_targets, to_report_formats, to_report_targets};
@@ -272,6 +272,7 @@ pub(crate) struct Kernel {
     pub(crate) strict: bool,
     pub(crate) timestamp: Timestamp,
     pub(crate) audit: Audit,
+    pub(crate) extid: ExtId,
     pub input: Input,
 }
 impl Kernel {
@@ -280,6 +281,7 @@ impl Kernel {
             strict: k_raw.strict,
             timestamp: Timestamp::from(&k_raw.timestamp)?,
             audit: Audit::from(&k_raw.audit)?,
+            extid: ExtId::from(k_raw.extid.as_ref()),
             input: Input::try_from(&k_raw.input)?,
         };
         Ok(k)
@@ -357,6 +359,19 @@ impl Audit {
     }
 }
 
+#[derive(Debug, Clone, Default)]
+pub(crate) struct ExtId {
+    pub(crate) unique: bool,
+}
+
+impl ExtId {
+    fn from(a_raw: Option<&ExtIdRaw>) -> ExtId {
+        ExtId {
+            unique: a_raw.is_some_and(|extid| extid.unique),
+        }
+    }
+}
+
 #[derive(Debug, Clone, Default)]
 pub struct Input {
     pub storage: StorageType,

tackler-core/src/config/raw_items.rs

@@ -21,6 +21,8 @@ pub(super) struct KernelRaw {
     pub(super) strict: bool,
     pub(super) timestamp: TimestampRaw,
     pub(super) audit: AuditRaw,
+    #[serde(rename = "ext-id")]
+    pub(super) extid: Option<ExtIdRaw>,
     pub(super) input: InputRaw,
 }
 
@@ -46,6 +48,13 @@ pub(super) struct AuditRaw {
     pub(super) mode: bool,
 }
 
+#[derive(Debug, Clone, Deserialize)]
+#[serde(deny_unknown_fields)]
+#[serde(rename = "ext-id")]
+pub(super) struct ExtIdRaw {
+    pub(super) unique: bool,
+}
+
 #[derive(Debug, Clone, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub(super) struct InputRaw {

tackler-core/src/kernel/settings.rs

@@ -217,6 +217,12 @@ impl Settings {
             ..Self::default()
         }
     }
+    #[must_use]
+    pub fn default_extid() -> Self {
+        let mut s = Settings::default();
+        s.kernel.extid.unique = true;
+        s
+    }
 }
 
 impl Settings {
@@ -396,6 +402,10 @@ impl Settings {
         }
     }
 
+    pub(crate) fn is_extid_unique(&self) -> bool {
+        self.kernel.extid.unique
+    }
+
     pub(crate) fn get_txn_account(
         &self,
         name: &str,

tackler-core/src/model/txn_data.rs

@@ -3,8 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-use crate::kernel::Predicate;
 use crate::kernel::hash::Hash;
+use crate::kernel::{Predicate, Settings};
 use crate::model::{TxnRefs, Txns, transaction};
 use crate::tackler;
 use itertools::Itertools;
@@ -18,6 +18,7 @@ pub struct TxnData {
     metadata: Option<Metadata>,
     txns: Txns,
     hash: Option<Hash>,
+    unique_extid: bool,
 }
 
 pub struct TxnSet<'a> {
@@ -54,21 +55,25 @@ impl TxnData {
     pub fn try_from(
         mdi_opt: Option<MetadataItem>,
         txns: Txns,
-        hash: &Option<Hash>,
+        settings: &Settings,
     ) -> Result<TxnData, tackler::Error> {
         let metadata = mdi_opt.map(Metadata::from_mdi);
 
-        if hash.is_some() {
+        if settings.audit_mode {
             check_uuids(&txns)?;
         }
+        if settings.is_extid_unique() {
+            check_extid(&txns)?;
+        }
 
         let mut t = txns;
         t.sort_by(transaction::ord_by_txn);
 
         Ok(TxnData {
             metadata,
             txns: t,
-            hash: hash.clone(),
+            hash: settings.get_hash().clone(),
+            unique_extid: settings.is_extid_unique(),
         })
     }
 
@@ -86,6 +91,9 @@ impl TxnData {
         if self.hash.is_some() {
             check_uuids(&self.txns)?;
         }
+        if self.unique_extid {
+            check_extid(&self.txns)?;
+        }
 
         let metadata =
             TxnData::make_metadata(self.hash.as_ref(), None, &self.txns.iter().collect())?;
@@ -150,6 +158,34 @@ impl TxnData {
     }
 }
 
+fn check_extid(txns: &Txns) -> Result<(), tackler::Error> {
+    let dups: Vec<&String> = txns
+        .iter()
+        .filter_map(|txn| txn.header.extid.as_ref())
+        .duplicates()
+        .collect();
+
+    if dups.is_empty() {
+        Ok(())
+    } else {
+        let dups_count = dups.len();
+        let msg = if dups_count < 10 {
+            format!(
+                "Found {} duplicate external ids.\nDuplicate ext-ids are:\n{}",
+                dups.len(),
+                dups.iter().join(",\n")
+            )
+        } else {
+            format!(
+                "Found {} duplicate external is.\nFirst ten duplicate ext-ids are:\n{}",
+                dups.len(),
+                dups[0..10].iter().join(",\n")
+            )
+        };
+        Err(msg.into())
+    }
+}
+
 fn check_uuids(txns: &Txns) -> Result<(), tackler::Error> {
     if txns.iter().any(|txn| txn.header.uuid.is_none()) {
         let msg =

tackler-core/src/parser/tackler_txns.rs

@@ -31,7 +31,7 @@ pub fn string_to_txns(
     // feature: a94d4a60-40dc-4ec0-97a3-eeb69399f01b
     // coverage: "sorted" tested by 200aad57-9275-4d16-bdad-2f1c484bcf17
 
-    TxnData::try_from(None, txns, &settings.get_hash())
+    TxnData::try_from(None, txns, settings)
 }
 
 /// # Errors
@@ -46,7 +46,7 @@ pub fn paths_to_txns(
         .flatten_ok()
         .collect();
 
-    TxnData::try_from(None, txns?, &settings.get_hash())
+    TxnData::try_from(None, txns?, settings)
 }
 
 /// # Errors
@@ -204,6 +204,9 @@ pub fn git_to_txns(
     // perf: let ts_end = SystemTime::now().duration_since(UNIX_EPOCH).unwrap(/*:test:*/);
     // perf: eprintln!("total time: {}ms, parse time: {}ms, git: {}ms", (ts_end.as_millis() - ts_start.as_millis()), ts_par_total, (ts_end.as_millis() - ts_start.as_millis())-ts_par_total);
 
-    let hash = &settings.get_hash();
-    TxnData::try_from(Some(MetadataItem::GitInputReference(gitmd)), txns?, hash)
+    TxnData::try_from(
+        Some(MetadataItem::GitInputReference(gitmd)),
+        txns?,
+        settings,
+    )
 }

tackler-core/tests/txns_extid.rs

@@ -0,0 +1,113 @@
+/*
+ * Tackler-NG 2026
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+mod txns_extid {
+    use indoc::formatdoc;
+    use std::fmt::Write;
+    use tackler_core::kernel::Settings;
+    use tackler_core::parser;
+    use tackler_rs::IndocUtils;
+
+    const EXT_ID_01: &str = "ext-id #001";
+    const EXT_ID_02: &str = "ext-id #002";
+    const EXT_ID_03: &str = "ext-id #003";
+
+    #[rustfmt::skip]
+    fn make_extids() -> String {
+        formatdoc!(
+            "2026-07-19 'txn01
+            | # ext-id: {EXT_ID_01}
+            | e  1
+            | a
+            |
+            |2026-07-19 'txn02
+            | # ext-id: {EXT_ID_02}
+            | e  1
+            | a
+            |
+            |2026-07-19 'txn03
+            | # ext-id: {EXT_ID_03}
+            | e  1
+            | a
+            |"
+        ).strip_margin()
+    }
+
+    #[rustfmt::skip]
+    fn dup_extid() -> String {
+        formatdoc!(
+            "2026-07-19 'txn04
+            | # ext-id: {EXT_ID_02}
+            | e  1
+            | a
+            |"
+        ).strip_margin()
+    }
+
+    #[rustfmt::skip]
+    fn make_dups_extid() -> String {
+        let mut s = make_extids();
+        _ = writeln!(s);
+        _ = writeln!(s, "{}", dup_extid());
+        s
+    }
+
+    #[test]
+    // test: f3c3f4fb-2c58-47d8-82a6-82b04a752e2e
+    // desc: try_from accepts duplicate ext-ids
+    fn txns_try_from_accepts_dup_extid() {
+        let txns =
+            parser::string_to_txns(&mut make_dups_extid().as_str(), &mut Settings::default());
+
+        assert!(txns.is_ok());
+    }
+
+    #[test]
+    // test: c4905afd-ea7a-460f-8f0b-ab46803f63be
+    // desc: try_from detects duplicate ext-ids
+    fn txns_try_from_detects_dup_extid() {
+        let txns = parser::string_to_txns(
+            &mut make_dups_extid().as_str(),
+            &mut Settings::default_extid(),
+        );
+
+        let err_msg = txns.expect_err("test case went wonky").to_string();
+
+        assert!(err_msg.contains("Found 1 duplicate"));
+        assert!(err_msg.contains("ext-id #002"));
+    }
+
+    #[test]
+    // test: 843948ac-6d7a-402e-9fe3-931615fd9565
+    // desc: append accepts duplicate ext-ids
+    fn txns_append_accepts_dup_extid() {
+        let mut txns = parser::string_to_txns(
+            &mut make_extids().as_str(), &mut Settings::default()).unwrap(/*:test:*/);
+
+        let mut txns_dup = parser::string_to_txns(
+            &mut dup_extid().as_str(), &mut Settings::default()).unwrap(/*:test:*/);
+
+        let res = txns.append(&mut txns_dup);
+
+        assert!(res.is_ok());
+    }
+
+    #[test]
+    // test: 1c8f8fb1-d96b-4661-8597-7ddda75194d5
+    // desc: append detects duplicate ext-ids
+    fn txns_append_detects_dup_extid() {
+        let mut txns = parser::string_to_txns(
+            &mut make_extids().as_str(), &mut Settings::default_extid()).unwrap(/*:test:*/);
+
+        let mut txns_dup = parser::string_to_txns(
+            &mut dup_extid().as_str(), &mut Settings::default()).unwrap(/*:test:*/);
+
+        let err = txns.append(&mut txns_dup);
+        let err_msg = err.expect_err("test case went wonky").to_string();
+
+        assert!(err_msg.contains("Found 1 duplicate"));
+        assert!(err_msg.contains("ext-id #002"));
+    }
+}