PM8
PatchMonger Waterfall Architecture
8-Tier Deterministic Token & Taxonomy Pipeline
BLACK FRIDAY READY • SUB-0.4ms PER PATCH
8-Tier Waterfall Specification & Audit Report

From cryptic composer stems to obscure beatmaker kits — decoded in eight deterministic tiers.

Sample libraries speak wildly different naming dialects. An orchestral scoring template stores 01_Violins_1_Leg_TMPro_C.nki seven directories deep; an underground trap pack stores Dark_808_Sub_140BPM_F#m.nki or BigFatModularBass.nki. PatchMonger runs an eight-stage pipeline combining 16KB binary header peeking, a 1,078-library catalog, folder family inheritance, greedy multi-word Trie tokenization (5,105 terms), and atomic word locking to turn every file into a clean Logic Pro .patch bundle.

8 Tiers
Deterministic Explainable Trace
1,078 Libraries
Across 44 Commercial Developers
9 Ecosystems
Kontakt • AU • EXS • Opus • VSL • Battery • BFD3 • NKS • Decent
5,105 Terms
6 Physical + 2 Virtual Taxonomies (NKS, Orchestral, Producer, GM, Technique, Sachs, Hybrid)
Symphonic & Film Composers UACC / ARTICULATION MATRIX

Understands orchestral desk numbers (Violins 1, Horns 2), context-guarded shorthand (st → Staccato, cs → Con Sordino, tpt, cb), single-letter mic suffixes (_C Close, _T Tree, _A Ambient, _O Outrigger), dynamic layers (ff, mp, RR1), and folder inheritance when files are simply named Legato.nki.

INPUT: .../Cinematic Studio Strings/01 Violins 1/Legato.nki
OUTPUT: Violins 1 - Legato - Cinematic Studio Strings -- Cinematic Studio.patch
Beatmakers & Electronic Producers 808s / BPM & KEY / CAMELCASE

Safeguards drum & synth icons (808, 909, 303, 106, 2600) from SKU stripping, splits CamelCase (BigFatModularBass → Big Fat Modular Bass) without shredding unseparated names, recognizes key signatures (F#m, Cmin, Bb Major) and tempos (140BPM, 128 BPM) as orange descriptors, and inherits 808s/, Plucks/, or Arps/ folder families.

INPUT: .../IndiePack/Trap_Kit/808s/Dark_808_Sub_140BPM_F#m.nki
OUTPUT: Dark 808 Sub - 140BPM F#m - Trap Kit -- NI.patch
Interactive Walkthrough

Live 8-Tier Waterfall Simulator

Pick any Composer or Beatmaker test fixture below—or type your own sample path and filename—to watch all eight tiers classify tokens, fire Patterns A–E & K, and route the Logic Pro .patch destination folder live.

Composer & Orchestral Presets 6 Fixtures
Beatmaker & Sound Design Presets 6 Fixtures
Resolved Token Pipeline (Teal = Instrument • Purple = Articulation • Orange = Descriptor • Green = Library • Indigo = Developer • Yellow = Word)
Logic Pro Category Path
Rendered .patch Bundle Filename
Ecosystem & Authority
Architecture Reference

How All 8 Tiers Execute in Sequence

Every candidate passes sequentially from raw bytes and OS file paths to canonical Logic Pro .patch taxonomy routing. Every tier emits structured telemetry into TokenTraceInspectorSheet so producers never have to guess why a sound was named or filed a certain way.

01
Ingestion

Input Ingestion & Binary Metadata Peek

BinaryMetadataPeeker.swift

Identifies the source sampler format across all 9 verified sampler ecosystems (Kontakt 5–8 NISound, AudioUnit .component, Logic Sampler .exs, EastWest Opus .opb, VSL Synchron .nksf, NI Battery 4 .nbkt, BFD3 Drums .bfd3kit, Universal NKS .nksf, Decent Sampler .dspreset). For .nki files, reads the local Kontakt SQLite database, walks up 5 levels for .nicnt XML ProductHints, and scans the first 16KB UTF-16LE DSIN header using alignment-safe byte reads on ARM64 to extract canonical Preset, Library, and Vendor strings while ignoring promo URLs and composer credits.

  • Strips legacy _LOCK suffixes & W64/K11 header noise
  • Authoritative Kontakt 8 DB overrides raw header guess
  • Unlocks non-NKI samplers from Tier 1 onward
  • Preserves Native Access Content Dir remapping
Binary Header Example
01 CineBrass SONORE... → Dev: "Cinesamples", Lib: "CineBrass Sonore"
02
Sanitize

Sanitization, Prefix & SKU Guarded Stripping + Splitting

FolderScanner+CatalogMatching.swift & +Phrasing.swift

Removes meaningless bracketed indices ([469], (001)), leading track numbers (01 -), and ALL-CAPS vendor SKU codes (SPIT-01 -, HVC_102 -) while strictly protecting hardware synth/drum models (808, 909, 303, 106, 2600), musical adjectives (Dark_808_, Juno_106_, Violin_1_), and decades (50s, 80s). Expands CamelCase safely and splits on structural delimiters while preserving intra-word hyphens (Hi-Hat, CS-80) and apostrophes.

  • All-caps-only SKU rule protects Beatmaker prefixes
  • Preserves player desk numbers (Violin 1, 2)
  • Leaves intra-word hyphens (Hi-Hat) intact
  • Splits underscores, --, :, |, ~, +
Normalization Guard
"SPIT-01 - Dark_808_Sub" → Strip "SPIT-01", keep "Dark_808_Sub"
03
Catalog

Authoritative 1,078-Library Catalog Matching

PatchDatabase.swift + nki_developer_catalog.json

Queries SQLite WAL across 1,078 curated commercial libraries across 44 developers (v2.3.0), passing both the file path AND the binary/.nicnt hints recovered in Tier 1. Uses strict path+vendor containment checks (preventing cross-developer contamination such as ARIA vs. Impact Soundworks) and supplies known per-library articulations, descriptors, and authoritative NKS subcategories.

  • Developer alias equivalence (ARIA ↔ Aria Sounds)
  • Self-healing clears stale catalogEntryId on mismatch
  • Receives binary metadata hints during trace generation
  • Zero-copy cached SQLite WAL lookup
Catalog Output
8Dio CASE Solo Brass → Primary: "03 Brass/05 Brass Ensemble"
04
Path Mine

Machine-Agnostic Path Folder Mining

FolderScanner+Tokenization.swift

Extracts musical hierarchy directories above the patch for all 8 file-based sampler ecosystems while stripping volume mounts (/Volumes/Samsung_T7_Studio/), foreign user home paths (/Users/other_producer/), /Users/Shared, and generic containers (Instruments/, Patches/). Scans mined folders against the shared 85+ term canonicalFamilyNouns table for Composer section desks and Beatmaker kit folders.

  • Covers Composers: Contrabasses, Cor Anglais, Timpani
  • Covers Beatmakers: 808s, Plucks, Arps, Braams
  • Strips numbered folder prefixes (01 Violins 1)
  • Shared uniformly across Catalog, Heuristics & Trace
Enclosing Context
.../Strings/01 Violins 1/Legato.nki → Inherit Noun: "Violins 1"
05
Tokenizer

Greedy 5-Down-to-1 Multi-Word Phrase Tokenizer

FolderScanner+Phrasing.swift & TokenDictionaryStore

Runs a pre-pass 2-word lookahead for beatmaker tempo & key pairs (128 BPM, F# Min, Bb Major) BEFORE catalog-ID checks so 3-digit BPMs are never discarded, then scans 5-to-1 word windows with morphological inflection support (-s, -es, Italian plurals celli/cello) against 5,105 merged dictionary terms (+ 72 articulation abbreviations) plus compact beatmaker keys (F#m, Cmin, Am), dynamics (ff, mp), and round-robins (RR1, CC11).

  • Priority hierarchy keeps Bells, Keys, Cymbal as .instrument
  • Longest multi-word match wins (French Horn, Sul Ponticello)
  • Context-aware abbreviations (st in strings → Staccato)
  • Trailing player numbers (Violins 1) stay attached
Tokenized Chips
[Instrument: Dark 808] [Descriptor: Sub] [Descriptor: 140BPM] [Descriptor: F#m]
06
Heuristics

Heuristic Patterns A–E & Atomic Word Locking

FolderScanner+Heuristics.swift & +CatalogMatching.swift

Enforces domain invariants across both Catalog and Non-Catalog files cleanly: locks unseparated compound instrument names (BigFatModularBass, Solo Pizzicato Violin) so internal adjectives and pre-noun articulations are never ripped out of the core instrument name, while extracting valid trailing articulations (Xiao Legato, Bansuri Legato) and inheriting missing instrument nouns from parent directories.

  • Unified Catalog & Heuristic unseparated locking
  • Word-Locking strips locked instrument words from modifiers
  • Pattern E fires on articulation-only OR 808s/Warm - Dark
  • Generic descriptor noise (Standard, Basic) stripped if redundant
Invariants Enforced
"Solo Pizzicato Violin" → Locked [Instrument], 0 carved arts
07
Assembly

Schema Assembly & Subfolder Depth Synchronization

TaxonomyDefinitions.swift & PatchModels+Status.swift

Assembles tokens in the active taxonomy’s customizable defaultTokenOrder (default: [Instrument/Words] - [Articulation] - [Descriptor] - [Library] -- [Developer]), deduplicating repeated path/filename tokens using accent-insensitive equivalence. When Subfolder Depth is set to By Library, patches group under <Category>/<Library>/ while keeping all filename tokens intact; when set to By Instrument, patches nest under <Category>/<Instrument>/<Articulation>/ while pruning redundant [Instrument] and [Articulation] tokens from the filename whenever descriptors or unclassified words remain.

  • Respects custom user schema ordering & separators
  • Supports Omit Developer & manual token locking
  • Zero synthetic Standard/Main placeholder folders
  • Sanitizes macOS invalid path characters (/ → clean)
Dynamic Filename Sync
Depth=.instrument → "02 Bowed Strings/Solo Cello/Long/Close Mic - Albion ONE -- Spitfire.patch"
08
Classify

Multi-Taxonomy Classification & Live Markdown Router

TaxonomyClassifier.swift & TaxonomyClassifier+Rules.swift

Routes the assembled patch into its Logic Pro destination folder under the active taxonomy schema: Kontakt (NKS), Orchestral Families, Modern Producer (01 808s & Sub Bass), General MIDI, Playing Technique, Hornbostel–Sachs, or Hybrid Domain Rules (with collision-free lowercase o/m/k/g/p/h prefixes). Locked [Instrument] tokens strictly outrank conflicting parent folders so a Trumpet Legato.nki inside a mixed Strings and Brass/ folder still files safely under Brass.

  • Honors live user Markdown edits (Taxonomies/*.md)
  • Authoritative NKS catalog category wins when uncustomized
  • Bare-adjective immunity (Acoustic Choir → Choir, not Guitar)
  • Hybrid routes Acoustic ↔ Orchestral, Synths/808s ↔ Producer
Final Destination
01 Bass/05 Sub Bass/Dark 808 - Sub 140BPM F#m...patch
Domain Intelligence

Heuristic Patterns A–E & K + Atomic Word Locking

Beyond raw dictionary lookup, six battle-tested musical heuristics handle real-world library quirks cleanly across both film-scoring templates and modern sample packs.

A

Library Acronyms & Title Preservation

Detects canonical commercial titles and initials (CASE, CSS, Albion Colossus, Damage 2) and isolates them as Green Library tokens instead of breaking them into meaningless unknown words.

8Dio CASE Solo Brass → [Library: CASE Solo Brass]
B

Atomic Instrument & Word Locking

For unseparated filenames without structural delimiters ( - , _), locks the core compound phrase as an atomic Teal Instrument and prevents any articulation or descriptor from stealing its words, while extracting trailing articulations.

"Solo Pizzicato Violin" → [Instrument: Solo Pizzicato Violin]
C

Single-Letter Mic Position Suffixes

Identifies trailing _C (Close), _T (Tree), _A (Ambient), and _O (Outrigger) orchestral mic arrays as Orange Descriptors while guarding against musical keys like Trumpet in C or Clarinet in A.

"Vln1_Leg_C" → [Instrument: Vln1] - [Articulation: Legato] - [Descriptor: C]
D

Context-Guarded Micro-Articulations

Expands dense composer abbreviations (leg → Legato, spic → Spiccato, pizz → Pizzicato, marc → Marcato, tr → Trill, st → Staccato when orchestral context is active).

"Hns_cs_leg" → Horns - Con Sordino Legato
E

Enclosing Folder Family Inheritance

When a patch contains only an articulation or separated descriptors (Legato.nki under 01 Violins 1/ or Warm - Dark.nki under 808s/), inherits the missing Instrument family from its directory tree.

".../Contrabasses/Col Legno.nki" → Contrabasses - Col Legno
K

Compound Synonyms, Key/Tempo & Hardware Immunity

Coalesces compound instrument synonyms (808 Sub, 909 Snare, Cello Ensemble, Woodwind Section) & multi-word phrases across underscores, tags 140BPM/F#m, and shields hardware synths (DX7, TR-808, CS-80, Juno-106).

"Dark_808_Sub_140BPM_F#m" → Dark 808 Sub - 140BPM F#m
Waterfall Code Audit — Verified Fixes

Contradictions Resolved & Tightly Bound Rules Unbound

A complete line-by-line audit of FolderScanner+Waterfall.swift, +Heuristics.swift, +CatalogMatching.swift, +Phrasing.swift, +Tokenization.swift, and TokenDictionaryStore+Lookup.swift resolved 7 contradictions and tightly bound rules—all regression-verified in Swift.

Contradiction 1 Resolved

Two-Tier Structural vs. Underscore Delimiter Engine

Splitting on _ before multi-word matching shattered French_Horn_Sul_Ponticello and 128_BPM across single-word segments. Separating structural field delimiters (--, - , :) from word-joiner _ restores 5-down-to-2 greedy phrase matching across underscores.

Before "French_Horn_Sul_Ponticello" → [Word: French] [Inst: Horn] [Word: Sul] [Art: Ponticello].
After (Unified) Clause preserves '_' for phrasing → [Instrument: French Horn] - [Articulation: Sul Ponticello].
Contradiction 2 Resolved

Compound Synonym Coalescing & Standalone Sub Promotion

Role words like Sub, Ensemble, and Section broke away as trailing orange descriptors (Dark 808 - Sub, Cello - Ensemble), while standalone Dark_Sub_140BPM had zero instruments. Pass 2 now coalesces compound roles and promotes solo Sub patches.

Before "Dark_808_Sub_140BPM_F#m" → Dark 808 - Sub 140BPM F#m.
After [Instrument: Dark 808 Sub] - [Descriptor: 140BPM F#m] (routes cleanly to Sub Bass).
Contradiction 3 Resolved

Hardware Synth & Numbered Instrument SKU Firewall

Permissive alphanumeric SKU rules stripped iconic synthesizers (DX7, CS-80, TR-808, Juno-106) and player-numbered instruments (Pad1, Violin1, Kick01). Added hardware synth detection, CamelCase number splitting, and strict ALL-CAPS SKU gating.

Before "DX7_Electric_Piano" / "Pad1_Warm" → SKU regex deleted DX7 & Pad1!
After [Instrument: DX7 Electric Piano], [Instrument: Pad 1] - [Descriptor: Warm]; SPIT-01 still stripped.
Contradiction 4 Resolved

Catalog vs. Heuristic Unseparated Articulation Rules

Catalog matching extracted trailing articulations on unseparated files (Xiao Legato) while protecting middle articulations (Solo Pizzicato Violin). Both engines now lock pre-instrument words atomically and guard leading technical tags (140BPM, [Free]) from instrument merging.

Before "Solo Pizzicato Violin" carved Pizzicato; "140BPM_808_Sub" merged 140BPM into Inst.
After Technical tags stay Descriptors; pre-instrument middle articulations stay locked.
Tightly Bound Rule Unbound

Dual-Role Playing Techniques Contextual Disambiguation

24 dictionary words overlap between instruments and articulations (Arp, Slap, Rimshot, Pulse). Following a concrete instrument in the same clause, Pass 2 now demotes the trailing technique to purple [Articulation] instead of gluing two nouns.

Before "Electric_Bass_Slap" / "Synth_Pluck_Arp" → single glued instrument noun.
After [Inst: Electric Bass] - [Art: Slap]; [Inst: Synth Pluck] - [Art: Arp].
Tightly Bound Rule Unbound

Multi-Ecosystem Path Mining, 85+ Families & BPM Lookahead

Unified Tier 4 folder mining across .opb/.exs/.nbkt/.bfd3kit/.nksf/.dspreset, centralized canonicalFamilyNouns and hasOrchestralContext, moved 2-word 128 BPM / F# Min lookahead ahead of SNPID stripping, and surfaced binary/.nicnt hints in Tiers 1 & 3.

Before Non-NKI starved Tier 4; "128_BPM" dropped 128; hardcoded "xiao" checks.
After Zero special-case hacks; unified ecosystem trace & composer/beatmaker coverage.