symusic-dependency-taste

name	symusic-dependency-taste
description	Decision framework for selecting and evolving third-party dependencies in symusic across C++, Python packaging, bindings, testing, and docs.
metadata	{"domain":"symusic","role":"dependency-architecture-advisor","scope":"dependency-selection-and-governance","output-format":"decision-record-and-checklist"}

Symusic Dependency Taste and Selection Framework

Use this skill when adding, replacing, or auditing dependencies.

High-Level Dependency Philosophy

1. Prefer focused libraries with clear performance or ergonomics wins.

   • Symusic favors small, purpose-built components (parser, serializer, binding layer) over heavy frameworks.

2. Keep the dependency surface narrow and intentional.

   • Every added dependency increases wheel complexity, ABI risk, cross-platform CI cost, and maintenance burden.

3. Keep core competency in-repo; outsource commodity building blocks.

   • MIDI-domain semantics and transformation logic should stay first-party.
   • Generic concerns (formatting, UTF-8 helpers, serialization primitives) can be external.

4. Choose libraries that align with cross-platform wheels and modern toolchains.

   • Compatibility with C++20, Python 3.9+ wheels, and reproducible CI builds is non-negotiable.

Existing Stack Taste Analysis

C++/Core Dependencies

• minimidi: chosen for fast and lightweight MIDI parsing; tightly aligned with symusic's core mission.
• prestosynth: dedicated synthesis backend for SoundFont rendering, consistent with a focused audio-rendering layer.
• pyvec: optimized container bridge that complements shared-pointer semantics and Python interop patterns.
• nanobind: modern, efficient C++/Python binding layer; matches performance-first and typed API goals.
• fmt: pragmatic formatting utility that improves clarity and maintainability over manual string assembly.
• zpp_bits (header-only include): lightweight serialization building block for pickle support.
• utfcpp + small utility headers (unordered_dense, macros): low-level helpers kept lean and local where practical.

Taste signal: this is a deliberately modular high-performance stack with minimal overlap between libraries.

Python Runtime Dependencies

• numpy: foundational numerical ecosystem choice; necessary for array-oriented conversions and interoperability.
• pySmartDL: targeted utility for managed downloads in soundfont workflows.
• platformdirs: minimal, standard choice for per-platform cache/config path correctness.

Taste signal: runtime Python dependencies are intentionally few, stable, and functionally justified.

Test/Dev Dependencies

• pytest, pytest-cov, pytest-xdist: standard, scalable Python testing stack.
• mypy, ruff configuration in pyproject.toml: static and style guardrails with pragmatic exceptions.
• pretty_midi (optional test extra): used as ecosystem interop/reference check rather than core runtime requirement.

Taste signal: strong quality automation, but optional extras remain clearly separated from runtime essentials.

Dependency Decision Rubric (Use Before Adding Anything New)

A candidate dependency should pass all gates:

1. Problem clarity: Is there a repeated, non-trivial problem not already solved in-repo?
2. Scope fit: Does the library solve exactly that problem without pulling broad framework baggage?
3. Performance profile: Any predictable hot-path cost, memory overhead, or startup regression?
4. Build/distribution impact: Does it complicate wheels, ABI compatibility, or CI matrix reliability?
5. Maintenance health: Active releases, clear license, issue responsiveness, and transparent governance?
6. Fallback plan: Can we pin, patch, or replace it safely if upstream breaks?

If any gate fails, prefer a smaller alternative or an internal implementation.

Preferred Choices by Category

• Bindings: stay with nanobind unless there is a compelling ABI/performance blocker.
• Numerics interop: keep NumPy as the canonical Python array surface.
• Paths/platform behavior: prefer tiny standard helpers like platformdirs over custom OS branching.
• Formatting/logging in C++: keep fmt style consistency.
• Serialization: keep lightweight binary serialization approaches; avoid monolithic runtime frameworks.

Red Flags (Usually Reject)

• Dependencies that duplicate existing stack capabilities with no measurable win.
• Libraries with unstable release cadence or unclear licensing.
• New runtime dependencies that are only needed for niche workflows (move those to optional extras).
• Python-only workarounds for problems best solved once in C++ core.
• Heavy frameworks that increase import/build time for marginal convenience.

How to Document a Dependency Change

For every addition/removal, include a short dependency decision record:

• Context: what limitation or pain point triggered the change?
• Decision: chosen library/version and integration boundary.
• Alternatives considered: at least one rejected option and why.
• Consequences: performance, binary size, CI, maintenance, and user-facing impact.
• Rollback strategy: how to safely revert or swap in future.

Minimal PR Checklist for Dependency Changes

• Runtime vs optional extra placement is correct.
• Lock/build metadata updated consistently.
• Cross-platform build path is validated.
• Tests cover new integration boundary.
• Docs mention user-visible installation/runtime implications.