environments and packages: provisioning layout, locks, registry, and `audio packages`

[fyang0507]

Context

TRANSCRIBE_DESIGN_HANDOFF.md opens the design work as seven
items. This issue takes the provisioning half of them — handoff open item 3 (the
environment layout, concretely), the transport half of item 2 (how a stage runs in an
environment that is not the tool's own), and everything audio packages needs to exist.
#12 takes the backend half.
The seam between the two is stated below and is worth reading before either starts.

This one comes first because it can invalidate the other's layout, not because it is
foundational in the abstract. The handoff's suggested sequence puts one uv resolution
attempt at step 1 for exactly that reason.

The naming contract is VOCABULARY.md §"Packages and environments"; the
command surface is TRANSCRIBE_CONTRACT.md §0 and §6; the output
shapes to diff against are TRANSCRIBE_HAPPY_PATH.md §1.3 and §5.
None of it is built.

The experiment that comes first

Question: can vibevoice-asr-7b, qwen3-forcedaligner, and firered-asr2s share one
locked Python environment? VOCABULARY declares three provisioned environments as the floor
and marks this joint resolution unverified. If it fails, torch splits, three
environments becomes four, and the plan's environment-spanning claims change.

The evidence already on this machine says the answer is probably no, and says why. The three
source checkouts each carry their own .venv, and those venvs — which are what actually
produced every recorded figure — disagree on a major version:

Checkout	torch	transformers	huggingface_hub	numpy
model_tests/firered/FireRedASR2S/.venv	2.10.0	5.1.0	1.27.0	2.4.2
model_tests/forced_aligner/.venv	2.13.0	4.57.6	0.36.2	2.4.6
model_tests/vibevoice/VibeVoice/.venv	2.13.0	4.57.6	0.36.2	2.4.6

(Read off *.dist-info under each venv's site-packages. The aligner venv also carries
qwen_asr==0.0.6 and qwen_omni_utils==0.0.9; VibeVoice carries diffusers==0.39.0.)

model_tests/vibevoice/VibeVoice/pyproject.toml declares transformers>=4.51.3,<5.0.0, so
FireRed's as-built transformers is outside VibeVoice's declared range. A single lock
satisfying both requires one of them to move, and moving either means re-running its recorded
evidence before any figure in model_tests/ still describes it.

Also worth knowing before trusting any tracked requirement file:
model_tests/firered/FireRedASR2S/requirements.txt pins torch==2.1.0+cu118 and
transformers==4.51.3 against a CUDA index. Neither can be what ran on Apple Silicon, and
neither matches the venv above. The as-built venvs are the artifact; the upstream
requirement files are not. Do not lock from them.

So the experiment is not "attempt one resolution" but three questions in order:

1. Does a joint uv resolution of the three as-built dependency sets exist at all? Resolve
   only; do not install.
2. If it does not, is the conflict genuinely FireRed's transformers 5.x requirement, or did
   the venv drift upward from a floor that 4.57.6 also satisfies? This decides whether the
   split is forced or incidental, and a forced split is a different registry than an
   incidental one.
3. If FireRed genuinely needs transformers 5.x, what is the smallest split — torch plus
   torch-firered, or something that groups differently — and what does that do to
   environments_spanned for a firered + word_timestamps request?

Record the outcome as an evidence artifact, whichever way it goes, and cite the resolver
output. "They conflict" without the resolver's own message is not a result. A negative
result here is the cheap one; discovering it during implementation is not.

What is already decided

Do not redesign these; they have stated reasons in VOCABULARY and the contract.

• One root, AUDIO_PROCESSING_MODEL_CACHE when set, else the per-platform cache dir
  src/audio_cli/vad.py already resolves. Nothing provisioned beside a source checkout.
• registry.json, models/, envs/{mlx,torch,swift}/ is the declared tree.
• Locks live in this repository. pull materializes a lock; it never resolves "latest".
  This is what keeps the mlx-audio private batched API at the one version the source-hash
  guard expects.
• Provisioning is explicit and fails closed. pull is the only thing that downloads
  weights, builds the Swift product, or applies the VibeVoice patch. A transcription request
  never triggers any of them — it exits 3 with the pull line that would fix it.
• Only small hash-pinned artifacts auto-fetch, the way vad.py already does, digest
  check and atomic rename included.
• remove is reference-counted; purge reads the registry rather than shell history and
  reports reclaimable bytes first; both state that the HF cache may be shared.
• Hub weights stay in the HF cache. The registry records which revisions this tool
  materialized, rather than duplicating a snapshot.
• fix is a runnable command wherever a configuration exists that would work.

Design questions this issue answers

1. registry.json's schema. Unspecified today. It has to serve five readers with
   different needs: list (bytes, license, used_by_stacks), verify (digests, the
   mlx-audio source hash, applied patches, whether the Swift product runs), remove
   (reference counts, materialized Hub revisions), purge (everything, from a session with
   no history), and run's exit-3 check (is this package present, at this revision). Decide
   whether it is one document or a document plus per-package sidecars, and how it survives a
   crashed pull — a half-written registry that reads as provisioned is the failure mode
   that turns exit 3 into exit 1.
2. How an environment is created and located. uv venv from a tracked lock is the
   obvious mechanism (and this repo's convention), but the questions are: one lock file per
   environment or one project with extras; how the tool finds each environment's interpreter
   afterwards; what happens when the tool is installed via uv tool install and therefore
   has no project checkout to read locks from — the locks must ship in the wheel or be
   fetched, and pyproject.toml's [tool.hatch.build] include list currently ships neither.
3. Non-Python environments. swift has no interpreter: it is a build product plus one
   Core ML package, and swift may be absent (doctor reports that, does not fail).
   speaker-diarization-coreml is a separate package from fluidaudio in the declared
   tables and must stay one.
4. The VibeVoice patch. logits_to_keep is tracked under
   model_tests/benchmark/patches/. Decide where a patch lives in the shipped tool, how
   verify knows it is applied, and what --repair does when it is not.
5. Cross-environment invocation. Not the stage ordering — that is
   #12 — but the mechanism a
   torch stage is invoked through from a core-environment process, and what crosses that
   boundary. The recorded evidence used fresh subprocesses per stage
   (run_interview_pipeline.py), so a persistent worker is outside what was measured and
   needs its own justification. Whatever it is, it has to make "no two model stages resident
   at once" enforceable rather than aspirational.
6. audio doctor. Tool version and path, ffmpeg/ffprobe/swift/uv presence, platform,
   memory, disk, resolved root, per-environment and per-package state.
7. Testing this without downloading 32 GB. The registry, reference counting, purge --dry-run, exit 3, and the integrity-failure path are all testable against a fabricated
   root. Decide what the fake root looks like and which parts genuinely require a live pull
   (live marker already exists in pyproject.toml).

The seam with #12

One table, two owners, and it must not become two tables.

• This issue owns the package/environment columns: package id, environment, kind,
  revision, digest, bytes, license, requires_tool, and the (stack, want) → package set
  mapping that pull --stack S --want ... and run's exit-3 check both consume.
• transcribe backend: adapter contract, result schema, stack table, planner, orchestration #12 owns the capability columns: availability, satisfaction, evidence, notes, and the
  planner that reads them.
• The interface between them is (stack, requirements) → [package]. transcribe backend: adapter contract, result schema, stack table, planner, orchestration #12 produces it, this
  issue consumes it. Until transcribe backend: adapter contract, result schema, stack table, planner, orchestration #12 lands, stub it — but stub it as the real function signature,
  not as a hardcoded list inside the packages command, or the two will disagree exactly once
  and silently.

Acceptance

• The torch resolution question is answered by a recorded resolver run, and VOCABULARY's
  environment table plus its "unverified" note are updated to match — including the split and
  its reason if it splits.
• registry.json has a written schema, and a crashed pull cannot leave a root that reads
  as provisioned.
• audio packages list | pull | verify | remove | purge | path and audio doctor produce the
  key sets in TRANSCRIBE_HAPPY_PATH §1.3 and §5 — including environments_kept_reason,
  hub_cache_note, unsized_packages, and the non-blocking license_unreviewed warning.
• remove on vibevoice-asr-7b keeps torch while the aligner and firered-asr2s need it,
  and says so.
• run before pull exits 3 with packages_not_provisioned and a fix line that, run
  verbatim, provisions exactly the missing set. A digest/size/revision mismatch exits 3 with
  package_integrity_failed and --repair.
• uv run --extra dev pytest stays green; the enhance render-from-original path is not
  regressed.

Traps

• A claim about a package must cite the artifact, not a summary. The handoff's process
  rule exists because three documents agreed on something no artifact supported. The
  requirements-file-versus-venv divergence above is the same failure shape, one layer down.
• Do not add registry structure nobody dispatches on. The capabilities report shed four
  nested objects for exactly this reason. If no command branches on a field, it is a note.
• Do not describe machinery that does not exist. If verify declares it checks applied
  patches, write the test that fails when a patch is reverted, and check that it can fail.

[fyang0507]

The layout is settled, derived rather than chosen

2eaa429. The torch environment does not resolve, so the split this issue anticipated is
real — but the membership is not what the spec assumed, and that turned out to matter more than
the count.

The partition

Every non-empty grouping of the dependency-contributing packages went to uv. Fifteen tested,
ten conflict, and all ten conflict on transformers — not one is about torch, numpy, or a
platform wheel. Four packages, three mutually exclusive ranges:

Package	Requires transformers	Via
Qwen ASR checkpoints	>=5.5.0,<5.13.0	mlx-audio==0.4.5
firered-asr2s	==5.1.0	its own pyproject.toml
forced aligner (torch path)	==4.57.6	qwen-asr==0.0.6
vibevoice-asr-7b	>=4.51.3,<5.0.0	its own pyproject.toml

Only the last two intersect. The probe also confirms the minimum is unique, so the layout
carries no undocumented choice between equally small alternatives — which "minimal" alone would
not have told us. run_env_partition_probe.py re-derives it whenever a pin moves.

Answering question 2 from the issue: the FireRed pin is upstream and forced, not local
drift. The checkout is clean at 4e7d9aa and its pyproject.toml is what pins 5.1.0. Two
traps found on the way, both live:

• FireRed ships two contradictory dependency files. requirements.txt pins
  torch==2.1.0+cu118 and transformers==4.51.3 against a CUDA index — impossible on Apple
  Silicon, and disagreeing with the pyproject.toml the working venv came from. The as-built
  environment is the artifact; an upstream requirement file is not.
• FireRed's LID stage has an undeclared dependency. fireredlid/data/feat.py:7 imports
  kaldi_native_fbank, which pyproject.toml never lists. Provision strictly from upstream
  metadata and --lid on fails at import on an otherwise correct environment.

The collapse probes

mlx-audio==0.4.5 — already pinned, already required — ships MLX implementations of all three
PyTorch-side components. So all three were rerun against their recorded cases
(results/2026-08-17-mlx-collapse-probes.json):

Aligner: equivalent, moved to mlx. Identical token text on all 246 aligned tokens,
all 17 word-bearing segments matching, both non-speech segments staying wordless, zero
punctuation-invariant violations. Bounds agree at median 0 s, P95 80 ms, max 1.6 s, with the
tail in long English filler-heavy segments. Neither path is scored against labels, so the tail
is the honest cost. The payoff: word_timestamps on a Qwen stack no longer pulls in a PyTorch
environment, so the fast long-form path spans two environments instead of three.

VibeVoice: not equivalent, did not move. 47 segments against 49 on identical
sha256-verified audio, full coverage both sides, some orthography shifted to traditional forms,
one lexical difference (蓝印车站 → 男人車站), and one non-speech tag disagreeing. 8-bit and
bf16 produce identical text, so this is the implementation and not quantization. The memory
case is nonetheless real:

Configuration	Peak	Generate (149.9 s)
torch bf16 + patch	20.84 GB MPS	79.7 s
MLX bf16	20.74 GB	275.1 s
MLX 8-bit	12.43 GB	56.3 s

12.4 GB is the first VibeVoice figure that does not immediately rule out a 16 GiB machine — the
"16 GiB is not validated" warning is about the 20 GB path. But adopting MLX replaces every
recorded VibeVoice figure, so it is a re-measurement decision, not a lock change.
torch-vibevoice is marked provisional and is deleted, not edited, when that decision lands.

FireRed: cannot move. mlx-audio's fireredasr2 is the AED only, and mlx-audio ships no
punctuation model anywhere — every punc hit in the package is TTS text normalization.
mlx-community publishes FireRedASR2-AED-mlx and nothing for FireRedPunc/LID/VAD. Punctuated
text is a floor, so moving only the AED would split one stack across two environments.

Mechanism

uv venv --python <pinned> then uv pip sync <lock>, from hash-pinned locks that ship inside
the wheel (verified: the built wheel contains all three locks, the manifest, and the inputs).
Validated end to end — an environment built from locks/mlx.txt reproduces the as-built pins
and hashes byte-identical on mlx_audio/.../qwen3_asr.py
(c082690575eedcd28fb76207d032cefd7eac2f9ce5d36df5a7a06575bc45d250), matching the pinned
guard. Both probes then ran in it. verify can check that hash and the private-API signature
without loading a checkpoint.

Registry schema, crash safety (state: pulling written before bytes move, so a crashed pull
reads as absent to run and as reclaimable to purge), derived-never-stored reference counts,
and the stage transport are all in ENVIRONMENTS.md. One consequence worth
flagging for #12: because a stage runs in a fresh subprocess against its own interpreter, no
model object can cross the boundary — the adapter-normalization floor becomes structural rather
than a rule someone has to remember.

Gaps closed on the side

• Byte sizes: every package now has a real count read at its pinned revision. fluidaudio
  alone stays unsized because it is a build product. Several spec figures were wrong rather
  than illustrative — microsoft/VibeVoice-ASR is 16.16 GiB not 17.0, and
  speaker-diarization-coreml is 129 MB not 84.
• Licenses: all declared now. license split into license_declared and
  license_reviewed, because a card is not a clearance and one field could not tell "nobody
  looked" from "the card says apache-2.0 and nobody checked what it obliges".
• Revisions: recovered for every package from the recorded runs' own
  .cache/huggingface/download/*.metadata, so the manifest pins what actually ran.

Spec documents updated for the new layout (VOCABULARY, contract, happy path, HANDOFF, design
handoff), and tests/test_environments.py locks it down — including a test that fails if a spec
document names an environment the manifest does not define, which is exactly how
"environment": "torch" would have outlived the environment called torch. All three new
assertions were confirmed to fail when violated. uv run --extra dev pytest green at 66 tests.

Not done

audio packages and audio doctor are not implemented — the data and the mechanism they need
are in place and validated, the commands are not written. That is what is left on this issue.

Follow-ups worth their own issues: the VibeVoice re-measurement decision, and the unevaluated
FireRed auxiliary conversions (an ONNX FireRedPunc would run in core, which already carries
onnxruntime — if it works, torch-firered becomes questionable too). Recorded but untouched:
mlx-audio also ships sortformer, a diarizer, so even swift has an MLX candidate.

[fyang0507]

audio packages and audio doctor are implemented

6603298. Lifecycle is list | path | pull | verify | remove | purge, plus doctor. 26 tests
against a fabricated root with uv and the downloader injected, so the registry state machine,
reference counting, digest verification, and every payload shape are covered without a network
or a toolchain. Suite is 92 green.

Each rule from the issue has a test that fails when it is violated:

Rule	What the test does
A crashed pull cannot read as provisioned	Kills the fetcher mid-pull, asserts state: pulling, asserts exit-3 still fires, asserts purge can still name the orphan
Reference counts derived, never stored	Removes two mlx packages in turn; the environment survives the first and goes with the second
purge reads the registry alone	A fresh Provisioner with no history finds and reports everything
A missing tool blocks only what needs it	swift absent → fluidaudio fails with requires_tool: ["swift"], the mlx package still pulls
verify failures must be reachable	Reverts a patch, drifts an environment, corrupts an artifact — each surfaces its own code and exit 3

Then the real pull found two things the fakes could not

This is the part worth reading. The suite was green before the first real pull ran, and the
real run still found two defects — both in the boundary the fakes stood in for:

1. pull wrote the Silero artifact under the wrong name. The filename was derived from the
version (6.2.1.onnx) while vad.py resolves silero-vad-6.2.1.onnx. Provisioning left two
copies on disk and the backend re-downloaded on first use anyway. The filename is manifest data
now, and a test ties it to vad.MODEL_FILENAME. Worth noting why the suite missed it: the fake
fetcher wrote wherever it was told, so the corruption test had been passing for the wrong
reason — it corrupted a file the registry did not point at.

2. Teardown overstated what it freed. Most of the bytes are Hub revisions rather than files
under the root, and nothing was deleting them — I had written a comment justifying that as
respecting a shared cache. But the payload said hub_revisions_deleted, so the report claimed a
deletion that never happened, and purge reported 2.47 GB reclaimed while freeing about 400 MB
of virtual environment. That is exactly the "do not describe machinery that does not exist" trap
from the design handoff, and VOCABULARY had already settled it: delete the recorded revisions,
and say so. It now deletes exactly the recorded commit hashes through the Hub cache's
revision-scoped deletion, leaves sibling revisions of the same repo alone, reports
hub_revisions_not_found separately, and measures reclaimed_bytes before deleting rather
than summing what the registry recorded. Verified end to end: a real purge freed 1.39 GB and the
repository directory went with it.

A third, milder one: the swift environment never got a registry entry, because it has no
interpreter to create — so purge could neither name it nor reclaim it.

End-to-end, against real weights

audio packages pull silero-vad          → 2,327,524 bytes, digest verified
audio packages pull qwen3-asr-1.7b-8bit → creates envs/mlx from the hash-pinned lock,
                                          materializes a8379a2e at 2,467,859,030 bytes
                                          — exactly the manifest's Hub figure
audio packages verify                   → mlx ok; private-API source hash AND signature
                                          confirmed without loading a checkpoint
audio packages remove / purge           → reference counting correct, 1.39 GB actually freed

inspect and enhance --dry-run unregressed.

One layout change

AUDIO_PROCESSING_MODEL_CACHE now overrides the root rather than the models directory, so
the tree matches VOCABULARY's whether or not the variable is set — previously the override put
the onnx at the top level and the default put it under models/. The default location is
unchanged; only the override case moves, and the one artifact affected auto-fetches.

What is left

The issue's acceptance list is now met except for the parts that belong to #12: pull --stack S --want ... currently selects every package a stack can use, because the (stack, requirements) → [package] function is the planner's. It is stubbed at the real signature —
environments.packages_for(stack, roles) — so #12 replaces it rather than paralleling it.
--want without --stack is refused rather than silently ignored.

Still open and worth their own issues: the VibeVoice re-measurement decision, and the
unevaluated FireRed auxiliary conversions.