sf-decomposer 6.17.0 → 6.19.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [6.19.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.18.0...v6.19.0) (2026-05-05)
+
+
+### Features
+
+* **metadata:** expand uniqueIdElements coverage from audit pass ([#439](https://github.com/mcarvin8/sf-decomposer/issues/439)) ([a4c6080](https://github.com/mcarvin8/sf-decomposer/commit/a4c6080fbafa0840ff9eb797351dd92ab1b0ecae))
+
+## [6.18.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.17.0...v6.18.0) (2026-05-05)
+
+
+### Features
+
+* **decompose:** bump config-disassembler to 1.2.1 and use compound keys for app ([#433](https://github.com/mcarvin8/sf-decomposer/issues/433)) ([c087664](https://github.com/mcarvin8/sf-decomposer/commit/c087664a44d73116bc375333275cb6f722662013))
+* **deps:** bump config-disassembler to 1.3.0 (sanitize + collision detection) ([#436](https://github.com/mcarvin8/sf-decomposer/issues/436)) ([d53878b](https://github.com/mcarvin8/sf-decomposer/commit/d53878b8c67b4ca42a35695b605b2c489bed5f6c))
+
 ## [6.17.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.16.0...v6.17.0) (2026-05-04)
 
 

package/HANDBOOK.md

@@ -126,9 +126,9 @@ Each dialog still gets its own folder, but steps live as flat `*.botSteps-meta.x
 >
 > The default still applies to every other bot.
 
-> **Agentforce vs Einstein.** Both share the `bot` suffix, so a single override entry covers both bot families. The structural difference (Agentforce uses richer `botFlowInvocation` and `genAi*` blocks where Einstein uses `botNavigation` and `mlIntents`) is invisible to this recipe — `multiLevel` rules only target the repeating sections that exist on each side. The plugin ships an `Internal_Copilot_Sample` fixture that exercises the Agentforce-style shape and an Einstein-style `Sample_Chat_Bot` fixture; both round-trip with the same recipe.
-
-> **Sibling order inside `botSteps`.** Recompose orders `<botSteps>` siblings alphabetically by their on-disk filename, not by their original document position. For bot deploys this is a no-op (Salesforce doesn't rely on step order at the XML level), but a freshly-recomposed file may show step entries shuffled compared to the source you originally pulled. The committed fixtures in this repo are baked from the recompose output for that reason — `sf decomposer verify` will treat the baked output as the source of truth.
+> **Agentforce vs Einstein.** Both share the `bot` suffix and are covered by a single override. Their structural differences (Agentforce: `botFlowInvocation`, `genAi*`; Einstein: `botNavigation`, `mlIntents`) are invisible to the recipe — `multiLevel` only targets the repeating sections that exist on each side.
+>
+> **Sibling order inside `botSteps`.** Recompose orders `<botSteps>` siblings alphabetically by on-disk filename, not by document position. Salesforce ignores step order at the XML level, so deploys are unaffected — but a freshly-recomposed file may show steps shuffled compared to the originally-retrieved source. The committed fixtures in this repo are baked from the recompose output for that reason; `sf decomposer verify` treats the baked output as the source of truth.
 
 ## Flexipages (Lightning App / Record / Home pages)
 
@@ -280,7 +280,7 @@ sf decomposer verify -t bot --config
 You probably ran two `decompose` invocations back-to-back, one rule each. Don't. The disassembler rewrites `.multi_level.json` on every run, so each call replaces the prior one. Pass every rule for a given component in **one** override entry, in array form.
 
 **2. "My `multiLevel` rule is correct but recompose produces a smaller file."**
-Almost always a unique-id collision. Two array items resolved to the same filename and one overwrote the other on disk. Add a tiebreaker to `unique_id_elements` (e.g. `developerName,id`) and re-decompose with `prePurge: true`.
+On `config-disassembler` Rust ≥ 0.5.0 / Node ≥ 1.3.0 this should not happen — sibling collisions are written to per-element SHA-256 shards and surfaced as a `WARN` (see pitfall #5), not silently overwritten. If you do see a shrunken recomposed file on a current build, treat it as a regression worth capturing as a fixture.
 
 **3. "Component-scope override fields look ignored."**
 Component-scope wins over type-scope, but only for fields **the component override explicitly sets**. Fields it leaves out fall through to the type-scope value, then to the run-wide default. If you set `decomposedFormat: "yaml"` on a type and `strategy: "grouped-by-tag"` on the component, the component still gets `decomposedFormat: "yaml"` from the type override.
@@ -289,7 +289,10 @@ Component-scope wins over type-scope, but only for fields **the component overri
 That's by design for `multiLevel` types only. Multi-level recompose has to clean up inner-level directories so the next level can merge their reassembled XML. If you want the decomposed tree preserved for inspection, copy it before running `recompose`.
 
 **5. "Decompose succeeded but my decomposed files all have hash names."**
-Your `unique_id_elements` (or the rule's third part) didn't resolve to a non-empty value on those items. Check the source XML for the elements you listed — names are case-sensitive and live at the immediate child level of each repeating item. The plugin only walks one level deep when picking a UID.
+There are two distinct causes; run the decompose under `RUST_LOG=warn` to tell them apart:
+
+- **No `WARN` line.** Your `unique_id_elements` (or the rule's third part) didn't resolve to a non-empty value on those items. Check the source XML for the elements you listed — names are case-sensitive and live at the immediate child level of each repeating item. The plugin only walks one level deep when picking a UID.
+- **A `WARN` line of the form `uniqueIdElements collision: <parentTag> id "X" matched N sibling elements`.** The configured key is too narrow — multiple siblings legitimately share the same value, so the collision detector falls back to per-element SHA-256 hashes for that group rather than overwrite. Add a tiebreaker to `unique_id_elements` (e.g. a compound like `name+recordType`) and re-decompose with `prePurge: true`.
 
 ---
 

package/README.md

@@ -14,29 +14,17 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
   <summary>Table of Contents</summary>
 
 - [Quick Start](#quick-start)
+- [Requirements](#requirements)
 - [Why sf-decomposer?](#why-sf-decomposer)
 - [Commands](#commands)
-  - [sf decomposer decompose](#sf-decomposer-decompose)
-  - [sf decomposer recompose](#sf-decomposer-recompose)
-  - [sf decomposer verify](#sf-decomposer-verify)
 - [Manifest-scoped runs](#manifest-scoped-runs)
 - [Decompose Strategies](#decompose-strategies)
-  - [Custom Labels](#custom-labels-decomposition)
-  - [Permission Sets (grouped-by-tag)](#additional-permission-set-decomposition)
-  - [Loyalty Program Setup](#loyalty-program-setup-decomposition)
 - [Supported Metadata](#supported-metadata)
-  - [Exceptions](#exceptions)
 - [Troubleshooting](#troubleshooting)
 - [Hooks](#hooks)
 - [Per-Type & Per-Component Overrides](#per-type--per-component-overrides)
-  - [splitTags grammar](#splittags-grammar)
-  - [multiLevel grammar](#multilevel-grammar)
 - [Ignore Files](#ignore-files)
-  - [.forceignore](#forceignore)
-  - [.sfdecomposerignore](#sfdecomposerignore)
-  - [.gitignore](#gitignore)
 - [Issues](#issues)
-- [Requirements](#requirements)
 - [Built With](#built-with)
 - [Contributing](#contributing)
 - [License](#license)
@@ -74,14 +62,7 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
    sf project deploy start
    ```
 
-   Or scope the recompose to just the components in your deploy manifest:
-
-   ```bash
-   sf decomposer recompose -x "manifest/package.xml"
-   sf project deploy start -x "manifest/package.xml"
-   ```
-
-   Or run the deploy command directly after configuring the [hooks](#hooks) to run the recompose automatically before deploying.
+   Pass `-x manifest/package.xml` to both commands to scope the run to the components in a deploy manifest. Configuring the [hooks](#hooks) automates this step entirely.
 
 ---
 
@@ -101,21 +82,14 @@ If other platforms or architectures require support, please open an issue in [co
 
 ## Why sf-decomposer?
 
-Salesforce’s built-in decomposition is limited. sf-decomposer gives admins and developers more control, flexibility, and better versioning.
-
-### Benefits
+Salesforce's built-in decomposition is limited. sf-decomposer gives admins and developers more control, flexibility, and better versioning.
 
-- **Broader metadata support** – Works with most Metadata API types, not just the subset Salesforce decomposes.
-- **Selective decomposition** – Decompose only what you need; use [.sfdecomposerignore](#sfdecomposerignore) to skip specific files.
-- **Manifest-scoped runs** – Pass `-x package.xml` to decompose or recompose only the components listed in a Salesforce manifest, mirroring `sf project deploy start -x`. Ideal for CI/CD pipelines that only ship a subset of metadata per deployment.
-- **Two [strategies](#decompose-strategies)**:
-  - **unique-id** (default): one file per nested element, named by content or hash.
-  - **grouped-by-tag**: one file per tag (e.g. all `fieldPermissions` in a permission set in `fieldPermissions.xml`). Use `--decompose-nested-permissions` for deeper permission set and muting permission set decomposition.
-- **Full decomposition** – Fully decompose types that Salesforce only partially supports (e.g. permission sets).
-- **Stable ordering** – Elements are sorted consistently to reduce noisy diffs.
-- **Multiple formats** – Output as XML, JSON, JSON5, or YAML.
-- **CI/CD hooks** – Auto decompose after retrieve and recompose before deploy via [.sfdecomposer.config.json](#hooks).
-- **Better reviews** – Smaller, structured files mean clearer pull requests and fewer merge conflicts.
+- **Broader metadata support** — works with most Metadata API types, not just the subset Salesforce decomposes.
+- **Two [strategies](#decompose-strategies)** — `unique-id` (one file per nested element) or `grouped-by-tag` (one file per tag).
+- **Multiple formats** — XML, JSON, JSON5, or YAML.
+- **Manifest-scoped runs** — pass `-x package.xml` to scope a run to just the components in a deploy manifest, the same way `sf project deploy start -x` does.
+- **CI/CD hooks** — auto-decompose after retrieve and auto-recompose before deploy via [.sfdecomposer.config.json](#hooks).
+- **Stable ordering and smaller files** — clearer pull requests, fewer merge conflicts.
 
 ---
 
@@ -238,22 +212,18 @@ sf decomposer verify -m "permissionset" -s "grouped-by-tag" -p
 sf decomposer verify -x "manifest/package.xml" --config
 ```
 
-Files where the **only** delta is sibling or attribute ordering are surfaced separately as informational notices ("Note: N file(s) round-tripped semantically but with sibling/attribute reordering") rather than as drift. This is safe — Salesforce treats metadata as order-agnostic and `config-disassembler` does not preserve original sibling order — but it tells you up front that committing the post-recompose output will produce a diff in git even though the metadata is functionally identical.
+Files whose **only** delta is sibling or attribute ordering are reported as informational notices, not drift. Salesforce treats metadata as order-agnostic, so the deploy is safe — the notice just warns that committing the post-recompose output will show a git diff even though the metadata is functionally identical.
 
 ---
 
 ## Manifest-scoped runs
 
-The `-x` / `--manifest` flag is supported by every `sf decomposer` command (`decompose`, `recompose`, `verify`) and accepts any standard Salesforce `package.xml`, limiting the work to just the components it lists. This is especially useful for CI/CD pipelines that deploy a subset of metadata per change.
+`-x` / `--manifest` is supported by every `sf decomposer` command and accepts the same `package.xml` you pass to `sf project deploy start -x`. Only the listed components are decomposed/recomposed; everything else is left alone.
 
-How it works:
-
-- The manifest is parsed with `@salesforce/source-deploy-retrieve`'s `ManifestResolver`, so the same XML you pass to `sf project deploy start -x` is honored here.
-- For each entry, the plugin resolves the matching parent metadata files in your local package directories (using each metadata type's `directoryName`, `suffix`, `strictDirectoryName`, and `folderType` from the SDR registry).
-- Only those files are decomposed/recomposed; everything else on disk is left untouched.
-- Wildcards (`<members>*</members>`) expand against your local source. Folder-typed members (e.g. `MyFolder/MyReport`) are resolved by walking the folder.
-- Types in the manifest that the plugin does not support (e.g. `CustomObject`, `ApexClass`) are skipped with a warning instead of failing the run, so a single manifest can drive both deploys and decomposer runs.
-- If both `--metadata-type` and `--manifest` are provided, the run is scoped to the intersection (only types present in both).
+- Wildcards (`<members>*</members>`) expand against your local source.
+- Folder members (e.g. `MyFolder/MyReport`) resolve by walking the folder.
+- Types the plugin does not support (e.g. `CustomObject`, `ApexClass`) are skipped with a warning, so the same manifest can drive both deploys and decomposer runs.
+- If both `--metadata-type` and `--manifest` are supplied, the run is scoped to the intersection.
 
 Example manifest:
 
@@ -329,9 +299,18 @@ permissionsets/
     └── userPermissions.xml
 ```
 
+### Filename safety (unique-id)
+
+Two safety nets apply automatically to every shard filename emitted by the **unique-id** strategy. Neither requires configuration:
+
+- **Path-segment sanitization (silent).** Characters illegal or reserved on at least one supported filesystem — path separators (`/`, `\`), Windows-reserved chars (`:`, `*`, `?`, `"`, `<`, `>`, `|`), and ASCII control bytes — are replaced with `_`; trailing `.` and spaces are stripped. Sanitized filenames are byte-stable across platforms.
+- **Sibling-collision fallback (emits `WARN`).** When two or more siblings of the same parent tag would resolve to the same filename (the configured unique-id elements are too narrow, or sanitization folded two distinct values together), every sibling in the colliding group is written to its own per-element SHA-256 shard instead. No row is silently overwritten.
+
+If you see a hash-named shard and want to know whether it came from a collision (vs. simply a missing UID), set `RUST_LOG=warn` and rerun — see [Rust crate logging](#xml-disassemble-output-rust-crate).
+
 ### Custom Labels Decomposition
 
-Custom labels use only the **unique-id** strategy. If you pass `grouped-by-tag`, the plugin overrides to `unique-id` and continues. Grouping labels by tag would produce no difference from the original file since all elements share the same tag. Each label is written to its own file.
+Custom labels are always decomposed with `unique-id` (grouped-by-tag would be a no-op since every element shares the same tag). Each label is written to its own file:
 
 ```
 labels/
@@ -373,12 +352,9 @@ permissionsets/
 
 ### Loyalty Program Setup Decomposition
 
-`loyaltyProgramSetup` supports only the **unique-id** strategy. If you pass `grouped-by-tag`, the plugin overrides to `unique-id` and continues. The metadata is automatically decomposed further under unique-id:
-
-- Each `<programProcesses>` element → its own file.
-- Each `<parameters>` and `<rules>` child → its own file.
+`loyaltyProgramSetup` is always decomposed with `unique-id`, with a built-in `multiLevel` default that splits `<programProcesses>` into per-process folders containing per-`<parameters>` / per-`<rules>` files.
 
-> Recomposition for loyalty program setup removes decomposed files even without `--postpurge`. Use version control or CI to keep them if needed.
+> Recompose for `loyaltyProgramSetup` always removes the decomposed tree, with or without `--postpurge`. Rely on version control if you need to inspect it after a deploy.
 
 ```
 loyaltyProgramSetups/
@@ -461,32 +437,31 @@ For example, if you attempt to decompose Custom Labels but none of your package
 
 ### XML disassemble output (Rust crate)
 
-The config-disassembler Node plugin uses a **Rust crate** for XML decomposing and recomposing. Disassemble errors and messages are shown in the terminal.
+The underlying Rust crate logs through [env_logger](https://docs.rs/env_logger). Set `RUST_LOG` to opt into more verbosity:
 
-Control verbosity with the `RUST_LOG` environment variable (e.g. `RUST_LOG=debug` for detailed output).
+| Level            | What it covers                                                                                                                                                                                |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RUST_LOG=error` | Default. Parse errors and skipped files (leaf-only XML — primitives only, nothing to decompose).                                                                                              |
+| `RUST_LOG=warn`  | Adds [sibling-collision fallback](#filename-safety-unique-id) signals — one line per colliding group (parent tag, collided id, sibling count). **Recommended in CI** when shipping overrides. |
 
-Example output in the terminal (Rust log format):
+Example `WARN` (CustomApplication where four `actionOverrides` siblings shared the action name `View`):
 
 ```
-[2026-04-30T12:34:38Z ERROR config_disassembler::xml::builders::build_disassembled_files] The XML file C:\Users\matthew.carvin\Documents\sf-decomposer\fixtures\package-dir-1\permissionsets\only_leafs.permissionset-meta.xml only has leaf elements. This file will not be disassembled.
+[2026-05-04T15:21:09Z WARN config_disassembler::xml::builders::build_disassembled_files]
+  uniqueIdElements collision: <actionOverrides> id "View" matched 4 sibling elements;
+  falling back to SHA-256 content hashes for the colliding group.
+  Consider adding more discriminating fields to uniqueIdElements for this metadata type.
 ```
 
-### Files with only leaf elements
-
-If a metadata file has only leaf elements (primitives, no nested structure), there is nothing to decompose. The Rust crate skips the file and logs an ERROR like the example above.
-
 ---
 
 ## Hooks
 
-> Configure [.forceignore](#forceignore) so the Salesforce CLI ignores decomposed files; otherwise `sf` commands can fail.
+Put **.sfdecomposer.config.json** in the project root to auto-decompose after `sf project retrieve start` and auto-recompose before `sf project deploy start` / `validate`.
 
-Put **.sfdecomposer.config.json** in the project root to run:
+> Configure [.forceignore](#forceignore) first — the Salesforce CLI must ignore decomposed files or `sf` commands can fail.
 
-- **After** `sf project retrieve start`: decompose.
-- **Before** `sf project deploy start` / `sf project deploy validate`: recompose.
-
-Copy and customize the [sample config](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.json), or the [sample config with overrides](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.overrides.json) to vary format/strategy/etc. by metadata type or by individual component.
+Copy and customize the [sample config](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.json), or the [sample with overrides](https://raw.githubusercontent.com/mcarvin8/sf-decomposer/main/examples/.sfdecomposer.config.overrides.json) to vary format/strategy per metadata type or component.
 
 | Option                       | Required    | Description                                                                                                                                                                                                                   |
 | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -584,7 +559,7 @@ For each component, each option is resolved independently in this order (highest
 
 Each `<tag>` may appear at most once in a spec. The plugin validates the grammar at config-load time. Deeper checks (e.g. unknown tag names for the metadata type) are surfaced by the underlying disassembler crate at runtime.
 
-#### splitTags cookbook
+**Examples:**
 
 ```json
 "overrides": [
@@ -597,21 +572,13 @@ Each `<tag>` may appear at most once in a spec. The plugin validates the grammar
     "metadataTypes": ["profile"],
     "strategy": "grouped-by-tag",
     "splitTags": "objectPermissions:split:object,fieldPermissions:group:field,layoutAssignments:group:layout"
-  },
-  {
-    "metadataTypes": ["flow"],
-    "strategy": "grouped-by-tag",
-    "splitTags": "actionCalls:split:name,decisions:split:name,assignments:split:name"
-  },
-  {
-    "metadataTypes": ["workflow"],
-    "strategy": "grouped-by-tag",
-    "splitTags": "rules:split:fullName,alerts:split:fullName,fieldUpdates:split:fullName,tasks:split:fullName"
   }
 ]
 ```
 
-> **Caveat:** When using `mode: split`, the chosen `<field>` must produce a unique value for every array item — otherwise two items would map to the same filename. If two items share a field value, prefer `mode: group` instead, which is designed for that case.
+> **Caveat:** With `mode: split`, the chosen `<field>` must produce a unique value across every array item — otherwise two items map to the same filename. If items can share a field value, use `mode: group` instead.
+
+See the [admin handbook](https://github.com/mcarvin8/sf-decomposer/blob/main/HANDBOOK.md) for additional `splitTags` and `multiLevel` recipes (flows, workflows, layouts, flexipages, bots).
 
 ### multiLevel grammar
 
@@ -651,13 +618,9 @@ Within one scope, the `(file_pattern, root_to_strip)` pair must be unique across
 ]
 ```
 
-> **`bot` and `loyaltyProgramSetup` ship with built-in `multiLevel` defaults**, so you don't need to add an override for either type to get the canonical decomposed layout — supply your own only if you want to replace the default. The full registry lives in [`src/metadata/multiLevelDefaults.ts`](https://github.com/mcarvin8/sf-decomposer/blob/main/src/metadata/multiLevelDefaults.ts).
-
-> **Why one call:** Pass every rule for a given component in a single override. Sequential single-rule decompositions rewrite the on-disk `.multi_level.json` and only the last rule survives — so multi-rule scenarios must travel together.
-
-> **Tip:** Use [`sf decomposer verify`](#sf-decomposer-verify) to non-destructively confirm a new override config still round-trips before committing it.
-
-> **Tip:** See the [admin handbook](https://github.com/mcarvin8/sf-decomposer/blob/main/HANDBOOK.md) for end-to-end recipes for Bots, Flexipages, Layouts, and other deeply-nested metadata.
+> **Built-in defaults.** `bot` and `loyaltyProgramSetup` ship with built-in `multiLevel` rules, so you do not need an override to get the canonical layout — supply your own only to replace the default. Full registry: [`src/metadata/multiLevelDefaults.ts`](https://github.com/mcarvin8/sf-decomposer/blob/main/src/metadata/multiLevelDefaults.ts).
+>
+> **Pass all rules at once.** Sequential single-rule decomposes rewrite `.multi_level.json` and only the last rule survives — bundle every rule for a given component into one override. Use [`sf decomposer verify`](#sf-decomposer-verify) to confirm a new config round-trips before committing it.
 
 ### Opting in from the CLI
 

package/lib/metadata/uniqueIdElements.d.ts

@@ -62,6 +62,15 @@ declare const _default: {
     reportType: {
         uniqueIdElements: string[];
     };
+    serviceChannel: {
+        uniqueIdElements: string[];
+    };
+    genAiPlugin: {
+        uniqueIdElements: string[];
+    };
+    app: {
+        uniqueIdElements: string[];
+    };
     mutingpermissionset: {
         uniqueIdElements: string[];
     };

package/lib/metadata/uniqueIdElements.js

@@ -144,9 +144,53 @@ export default [
             uniqueIdElements: ['sobjectType'],
         },
         reportType: {
-            // `<sections>` items use `<masterLabel>` as their natural key. Same
+            // `<sections>` items use `<masterLabel>` as their natural key — same
             // pattern as `globalValueSetTranslation`/`standardValueSetTranslation`.
-            uniqueIdElements: ['masterLabel'],
+            // The singleton `<join>` element is keyed by `<relationship>` purely for
+            // readability: without it every reportType that joins a child object
+            // produces a hash-named shard.
+            uniqueIdElements: ['masterLabel', 'relationship'],
+        },
+        serviceChannel: {
+            // Each `<serviceChannelStatusFieldMappings>` row carries `<type>` (a
+            // status category like `COMPLETED` / `IN_PROGRESS`) and `<value>` (the
+            // human-readable status name). `<type>` collides massively (most rows
+            // are `COMPLETED`) and `<value>` alone is usually unique within a
+            // channel, but we observed status names repeated across distinct types
+            // in production data — the compound `type+value` is the only fully
+            // stable id, with `value` as a single-field fallback for any row that
+            // happens to lack `<type>`.
+            uniqueIdElements: ['type+value', 'value'],
+        },
+        genAiPlugin: {
+            // `<genAiFunctions>` items are keyed by `<functionName>`;
+            // `<genAiPluginInstructions>` items by `<developerName>`. Each
+            // repeating child only carries one of these fields, so first-match
+            // wins picks the right one without a compound.
+            uniqueIdElements: ['functionName', 'developerName'],
+        },
+        app: {
+            // CustomApplication's `<profileActionOverrides>` and `<actionOverrides>`
+            // have a *compound* natural unique key: any single field (e.g. just
+            // `<actionName>`) collides for hundreds of siblings sharing
+            // `<actionName>View</actionName>`, silently merging on disassembly.
+            // Compound keys (config-disassembler >= 0.4.5) join the resolved values
+            // with `__` to form a stable, readable, collision-free filename.
+            //
+            // Fallback chain, widest first:
+            //   1. profileActionOverrides with recordType
+            //   2. profileActionOverrides without recordType
+            //   3. actionOverrides with recordType (no profile)
+            //   4. actionOverrides without recordType (no profile)
+            // Items missing `pageOrSobjectType` or `formFactor` (very rare) fall
+            // through to the SHA-256 outer-element hash, which is correct since
+            // we can't safely name them without those keys.
+            uniqueIdElements: [
+                'actionName+pageOrSobjectType+formFactor+profile+recordType',
+                'actionName+pageOrSobjectType+formFactor+profile',
+                'actionName+pageOrSobjectType+formFactor+recordType',
+                'actionName+pageOrSobjectType+formFactor',
+            ],
         },
         mutingpermissionset: {
             uniqueIdElements: [

package/lib/metadata/uniqueIdElements.js.map

@@ -1 +1 @@
-{"version":3,"file":"uniqueIdElements.js","sourceRoot":"","sources":["../../src/metadata/uniqueIdElements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"uniqueIdElements.js","sourceRoot":"","sources":["../../src/metadata/uniqueIdElements.ts"],"names":[],"mappings":"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"}

package/oclif.manifest.json

@@ -342,5 +342,5 @@
       ]
     }
   },
-  "version": "6.17.0"
+  "version": "6.19.0"
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "sf-decomposer",
   "description": "Split large Salesforce metadata files into version-control-friendly pieces and rebuild deployment-ready files.",
-  "version": "6.17.0",
+  "version": "6.19.0",
   "dependencies": {
     "@oclif/core": "^4",
     "@salesforce/core": "^8.26.3",
     "@salesforce/sf-plugins-core": "^12.2.6",
     "@salesforce/source-deploy-retrieve": "^12.35.0",
-    "config-disassembler": "^1.1.3",
+    "config-disassembler": "^1.3.0",
     "fast-xml-parser": "^5.7.2",
     "p-limit": "^7.3.0"
   },
@@ -95,6 +95,9 @@
     "test:only": "wireit",
     "test:perf": "vitest run --config ./vitest.perf.config.ts",
     "test:perf:gen": "node --import ts-node/esm scripts/gen-perf-fixtures.ts",
+    "audit": "node --loader ts-node/esm --no-warnings=ExperimentalWarning scripts/audit/audit.ts",
+    "audit:sweep": "node --loader ts-node/esm --no-warnings=ExperimentalWarning scripts/audit/sweep.ts",
+    "audit:roundtrip": "node --loader ts-node/esm --no-warnings=ExperimentalWarning scripts/audit/roundtrip.ts",
     "version": "oclif readme"
   },
   "publishConfig": {