vocal2midi-rs-dep-bootstrap

name	vocal2midi-rs-dep-bootstrap
description	Expand dependency sources and align canonical shared capabilities, Rust crate reuse, adapters, hand-written Burn gaps, fixtures, and bootstrap records for Vocal2Midi. Use before implementation when imports, native/FFI sources, dependency mismatch, shared model prerequisites, temporary dependency copies, Cargo coordination, or manifest re-cut decisions affect a unit.

Vocal2Midi Rust Dependency And Bootstrap

Prepare or re-cut migration units so implementation can start without guessing about dependencies, fixtures, or seam shape.

Required Context

Read these first:

• rewrite-in-rust/README.md
• rewrite-in-rust/manifest.yaml
• rewrite-in-rust/resources.md
• rewrite-in-rust/notes.md
• rewrite-in-rust/reference/glossary.md
• pyproject.toml
• uv.lock
• requirements.txt, requirements-linux.txt, requirements-web.txt
• third_party/README.md
• third_party/sources/manifest.json
• third_party/sources/MISSING_SOURCES.md
• third_party/native_sources/manifest.json
• third_party/source_audit.json
• Source refs and verification notes for the selected unit
• Execution policy, canonical shared dependency registry, and coordinator assignment when those records exist

Completion criterion: every dependency claim is grounded in a file or marked as an assumption.

Dependency Expansion Pass

Vocal2Midi intentionally keeps a large local third-party source corpus. Treat first-layer direct Python dependency source snapshots as the normal high-level reference material for dependency alignment and wheel rebuilding. They are reference sources, not automatic rewrite targets.

Start from the selected Python source refs, then search first-layer direct dependency sources before going deeper. Second-layer or deeper transitive dependency source expansion is allowed only when there is public-seam call path evidence that the selected behavior depends on a specific transitive implementation.

Inspect:

• project imports and local helper calls
• Python package requirements and lockfile entries
• third_party/sources/<package-version>/ for Python source distributions
• third_party/upstream_sources/<package-version>/ for packages without sdists
• third_party/native_sources/<library-version>/ for native/FFI source trees
• third_party/cargo_vendor/<source-path>/ for Rust-backed Python package crates
• existing tests, fixtures, and public caller expectations

For second-layer or deeper source, record the exact call path from the Vocal2Midi public behavior boundary to the transitive symbol, function, class, schema, native wrapper, data table, ABI contract, persistence format, model payload, cache key, or error projection. A lockfile dependency edge alone is not evidence.

Stop when the unit can name its behavior, dependencies, fixtures, rollback, and kept-legacy capabilities. Do not expand just to map the whole Python ecosystem.

Completion criterion: the unit boundary is confirmed or a re-cut is proposed.

Capability Coverage

Decide by capability, not by Python package name.

• Pure validation, parsing, formatting, alignment, and deterministic algorithms can be hand-written in Rust against fixtures.
• A Rust crate does not need to be a perfect drop-in to be useful. When a crate covers a stable lower layer, such as tokenization, parsing events, IO, Unicode tables, numeric primitives, or data structures, prefer reusing that layer and writing a small semantic-delta adapter for the Python-specific behavior it does not cover.
• If Python source for the legacy behavior is available in project files, third_party/, or another recorded source snapshot, use it to implement only the observed semantic delta between the Rust crate and Python behavior. Do not reject a crate merely because its high-level API disagrees with the Python package.
• Heavy model inference, ONNX Runtime, Qwen ASR, PyQt, and Flask remain legacy-owned unless the manifest changes.
• Local vendored Python, Rust, and native sources may be used as references.
• Use third_party/source_audit.json and the source manifests to justify the exact reference source path used for a semantic-delta adapter or hand-written replacement.
• A direct crate replacement is optional. Fewer Rust dependencies is not a success metric. Prefer maintained crates for stable lower-layer behavior when fixtures prove the fit, then hand-write the observed Python semantic delta.
• Full hand-written replacement is valid when it is smaller, safer, or easier to verify and roll back than crate reuse plus adapter. Record the tradeoff: semantic mismatch, licensing/security/build/runtime/portability/maintenance risk, excessive integration cost, or a capability so narrow that a crate adds more surface than it removes.
• If a planned unit is too broad after expansion, split it. If several units share the same required Rust data model or fixture harness, merge or extract a prerequisite unit.
• Burn is useful but does not cover every model capability needed by this rewrite. When multiple model units need the same missing Burn behavior, create one canonical project-controlled hand-written crate/adapter as a prerequisite; do not let each model writer implement a private version.
• Do not install or add bridge dependencies that the selected seam does not need.

Completion criterion: kept-legacy capabilities and Rust-covered capabilities are both named.

Behavior Verification

Every unit must name an independently comparable Python/legacy public seam before writer work. Record the observable tensor, codec, artifact, model-loading, error and workflow behavior that crosses that seam. Comparison is exact unless an existing public contract or explicit pre-implementation user decision records a model or numeric tolerance.

When framework internals would make the selected unit unverifiable, move the seam outward, re-cut the unit, or keep the capability legacy-owned. Do not use the new unit, canonical Rust units, compilation, or a failed parity test as a replacement oracle.

Shared Dependency Coordination

Search the canonical registry before adding crates or writing a dependency gap. Record one project path, owner shard, consumers, manifests, fixtures, and build evidence for shared implementations. A path under /tmp or an agent-private workspace is never canonical; promote useful work into rewrite-in-rust/rust/ or another recorded project root before another unit consumes it.

Default to serial execution. In coordinated parallel mode, workers may propose dependency changes but only the coordinator updates shared Cargo.toml, Cargo.lock, workspace membership, patch configuration, registry entries, or the Cargo build queue.

Native And Low-Level Boundary

Vocal2Midi uses Python as a glue layer over native and model ecosystems. Do not turn low-level compiler/runtime/native-library details into migration work just because they are visible in dependency source.

In scope when they affect the selected public behavior:

• parser state, tokenizer output, tensor shape/dtype policy, model runner payloads, serialization schema, cache keys, business DTOs, user-visible error projection, and Unicode normalization output

Ignore by default:

• NaN bit payloads, compiler macros, native struct padding, allocator behavior, SIMD branches, internal Unicode table layout, BLAS/CUDA kernel choice, and other implementation details that do not reach the public seam

Investigate low-level differences only when they can affect public outputs, errors, serialization, persistence, memory/ABI contracts, security, or model/numeric correctness.

Seam Default

The default seam is an independent Rust library plus fixtures under rewrite-in-rust/rust/. Do not introduce PyO3, CLI/subprocess, HTTP, or a Python runtime router during bootstrap unless the unit needs runtime promotion planning.

If a non-default seam is needed, record:

• seam kind
• public payload shape
• error mapping
• trace/log context
• repeated-call behavior
• rollback path

Completion criterion: the next writer can implement without choosing a new architecture.

Output

Write or update:

• rewrite-in-rust/dependencies/<unit-id>.yaml
• rewrite-in-rust/bootstrap/<unit-id>.md when a seam or fixture harness is proven
• rewrite-in-rust/records/NNNN-*.md when the decision changes a boundary or teaches a reusable lesson
• rewrite-in-rust/manifest.yaml when dependency discovery confirms, splits, merges, replaces, or defers provisional units
• the project canonical shared dependency registry when a capability has more than one consumer

Use this dependency record shape:

unit: unit_id
status: planned | active | done | blocked
capabilities:
  capability_name:
    legacy: "Python source or dependency"
    rust: "crate or narrow implementation"
    reason: "why this covers behavior"
seam:
  kind: library | ffi | cli | service | pipeline
  default_owner: legacy
  bridge_dependencies: []
canonical_dependency:
  registry: "rewrite-in-rust/shared-dependencies.yaml"
  reuse: []
  requested_changes: []
  temporary_sources: disposable_only
behavior_verification:
  legacy_public_seam: "Python model/application boundary"
  required_observations: []
  comparison_policy:
    default: exact
    tolerances: []
  evidence: []
fixtures:
  required:
    - "fixture or golden output needed before writer starts"
crate_reuse:
  candidates:
    - crate: "crate-name"
      covered_capabilities:
        - "what the crate can own safely"
      gaps:
        - "Python behavior not covered by crate"
      adapter_plan: "how the unit will patch the gaps using legacy source/fixtures"
      decision: use | reject | defer
dependency_strategy:
  stance: "reuse stable crate-owned lower layers; hand-write observed semantic gaps or a full replacement when the tradeoff says so"
  not_goal: "minimize dependency count"
  full_handwritten_allowed_when:
    - "crate semantic mismatch is larger than the selected capability"
    - "licensing, security, build, runtime, portability, or maintenance risk is unacceptable"
    - "a narrow fixture-backed implementation is smaller and easier to roll back"
source_expansion:
  first_layer_reference:
    status: indexed | missing | partial
    source_manifest: "third_party/sources/manifest.json"
  targeted_deep_expansion:
    used: true | false
    proof:
      - "public seam -> first-layer dependency -> transitive symbol/function/schema"
    rejected:
      - "lockfile transitivity without public-seam evidence"
low_level_boundary:
  ignored:
    - "native/compiler/runtime detail that does not affect public seam"
  investigated:
    - "public behavior, memory/ABI, persistence, security, or model/numeric correctness risk"
inventory_impact:
  decision: confirmed | split | merged | renamed | deferred | replaced
  reason: "why the manifest unit boundary did or did not change"
hand_written_replacements:
  - capability: "behavior implemented directly in Rust instead of by crate"
    reference_sources:
      - "third_party/sources/package-version or native/upstream/cargo source path"
    reason: "why this is better than crate reuse plus an adapter"
legacy_kept:
  - capability: "capability retained in Python"
    reason: "why not moving now"
verification:
  - "copyable command"

Completion criterion: output records are specific enough for vocal2midi-rs-unit-writer, or the manifest has been re-cut before writer work.

Checks

Run non-mutating checks where useful:

cargo test --manifest-path rewrite-in-rust/rust/Cargo.toml
uv run python scripts/audit_vendored_sources.py

If a required command fails because the environment is missing or blocked, report the exact blocker and do not pretend dependency alignment is complete.

Also check:

• first-layer direct dependency references are indexed or the missing source is recorded in third_party/sources/MISSING_SOURCES.md
• any second-layer or deeper source expansion has call-path evidence
• low-level native/compiler/runtime differences are ignored unless they affect the selected public seam or memory/ABI, persistence, security, or model/numeric correctness
• shared Burn gaps and other hand-written dependencies have one canonical path, owner, consumer list and verification record
• no reusable dependency points to /tmp or an agent-private workspace
• coordinated parallel workers did not modify shared Cargo files or bypass the coordinator's build queue
• every unit names a legacy public seam and tests application-level tensor, codec, artifact and model-loading behavior when it crosses that seam