Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.8.0): Hailuo H3 uses half the memory, and runs on smaller Macs
mrbizarrof97ea3c13c4c
diff --git a/VERSION b/VERSIONindex f6cdf40..88f1811 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.7.0+4.8.0diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex b7b6702..5f432c0 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -1257,6 +1257,10 @@ def get_settings_public() -> dict:"spicy_mode": bool(s.get("spicy_mode", False)),"memory_policy": s.get("memory_policy", DEFAULT_MEMORY_POLICY),"live_preview": str(s.get("live_preview", "on")),+ # Write-only until now: `update_settings` validated and stored it, but+ # the GET never returned it, so any control would open showing "auto"+ # no matter what the user had chosen.+ "h3_dit": str(s.get("h3_dit", "auto") or "auto"),"update_banner_dismissed": str(s.get("update_banner_dismissed", "") or ""),"star_prompt_done": bool(s.get("star_prompt_done", False)),# Analytics. Same has_X-boolean treatment as the other secrets —@@ -6977,6 +6981,37 @@ def _detect_total_ram_gb() -> float:SYSTEM_RAM_GB = _detect_total_ram_gb()+# The RAM floor of each tier, in GB. `_detect_tier()` gates on these AND+# `min_ram_gb_for()` quotes them, so a refusal can no longer name a number the+# gate does not use.+#+# THE BUG THIS CLOSES (@fiction, Pinokio, 2026-08-29 — "the high720P Q8 is not+# clickable"): four separate refusals told the user to "bump to 64+ GB" for+# High, Extend, FFLF and the HQ chip. All four are `allows_*` flags that the+# table grants on `standard`, whose floor is 48 — and the tier modal three+# clicks away says so in its own words ("48-79 GB ... Every video mode works").+# So the app simultaneously told a 36 GB owner to buy 64 and told them 48 was+# enough, and 16 GB of unnecessary hardware is an expensive way to find out+# which sentence was maintained.+TIER_MIN_RAM_GB: dict[str, int] = {+ "base": 0,+ "standard": 48,+ "high": 80,+ "pro": 120,+}+++def min_ram_gb_for(capability: str) -> int | None:+ """Lowest RAM in GB at which `capability` is True in CAPABILITIES.++ Returns None if no tier offers it — callers fall back to prose rather than+ printing "None GB", because a capability nothing serves is a bug in the+ table, not something to quote a number for.+ """+ floors = [TIER_MIN_RAM_GB[k] for k, caps in CAPABILITIES.items()+ if caps.get(capability) and k in TIER_MIN_RAM_GB]+ return min(floors) if floors else None+def _detect_tier() -> str:"""Pick a tier based on `hw.memsize`. Cached at module load — RAM is@@ -6988,9 +7023,9 @@ def _detect_tier() -> str:gb = SYSTEM_RAM_GBif gb <= 0:return "standard" # safe default- if gb < 48: return "base"- if gb < 80: return "standard"- if gb < 120: return "high"+ if gb < TIER_MIN_RAM_GB["standard"]: return "base"+ if gb < TIER_MIN_RAM_GB["high"]: return "standard"+ if gb < TIER_MIN_RAM_GB["pro"]: return "high"return "pro"@@ -7107,7 +7142,31 @@ H3_MIN_RAM_GB = 60.0# calls measured-safe) the render peak drops from 42.8 to 27.3 GiB measured at# 1024x576/124f — which puts H3 in reach of 48 GB Macs. 46 leaves the same# ~4 GB guard band under the marketing number that 60-under-64 does.-H3_MIN_RAM_GB_Q8 = 46.0+# LOWERED 46 -> 36 on 2026-08-29, on measurement rather than on a guard band.+#+# 46 was picked to sit ~4 GB under a 48 GB Mac's marketing number, back when the+# only number anyone had was "27.3 GiB peak". The full phase profile since then:+#+# text_encode 25.63 GiB <- the run peak, a 7-second phase+# dit_load 20.22+# joint_denoise 21.26 (5 s) / 24.68 (10 s)+# video_vae 8.42+#+# 25.63 GiB is 27.5 GB. The panel now also caps H3's memory budget so the render+# leaves the user real headroom (h3_memory_budget: the larger of 6 GB and RAM/8),+# where before it took everything but one gigabyte. 27.5 + 6 = 33.5, so a 36 GB+# Mac clears it with room; 48 GB was never the real requirement.+#+# EVIDENCE: Q8 rendered clean at a simulated 36 GB budget (--memory-gb 30+# --wired-gb 26) AND at a simulated 32 GB budget (26/22), both rc=0 and both+# byte-identical (sha256 ba65bc6a...) to the unconstrained render.+#+# 32 IS DELIBERATELY NOT THE FLOOR. 27.5 GB of peak on a 32 GB Mac leaves ~4.5+# GB for macOS and everything else, which is the "it's tight so you can't use+# your Mac" state the owner explicitly rejected. Those runs also simulated the+# limit on a 64 GB machine, which caps MLX without reproducing real pressure+# from the rest of the system. Moving to 32 needs a real 32 GB Mac, not a flag.+H3_MIN_RAM_GB_Q8 = 36.0H3_DIT_Q8_DIRNAME = "h3-dit-q8"H3_DIT_FILENAME = "MiniMax-H3-FL2VA-pruned_bf16.safetensors"H3_COMPACT_FILES = ("text_encoder.safetensors", "video_vae.safetensors",@@ -8886,7 +8945,8 @@ def ltx_tiers_payload() -> dict:f"Not available on the {SYSTEM_CAPS['label']} hardware "f"tier — the Q8 dev transformer (~19 GB) plus the "f"upscaler stage doesn't fit in this Mac's memory. "- f"Standard and Quick run here; High needs 64+ GB.")+ f"Standard and Quick run here; High needs "+ f"{min_ram_gb_for('allows_q8') or 48} GB or more.")return {"tiers": tiers,"qualities": [dict(q) for q in sorted(@@ -9033,6 +9093,99 @@ def _h3_venv_present() -> bool:return (venv / "pyvenv.cfg").is_file() or (venv / "bin" / "activate").is_file()+# =============================================================================+# H3 PROMPT-EMBEDDING CACHE — the 26 GB model that sets H3's memory ceiling+# =============================================================================+#+# MEASURED 2026-08-29, and it is not where anyone was looking. Per-phase peaks+# from the staged runner, identical across every arm to two decimals:+#+# text_encode_q8 25.71 GiB <- the RUN PEAK on the Q8 path+# dit_load 20.22 GiB (Q8) 38.56 GiB (bf16)+# joint_denoise 21.28 GiB (5 s) 24.68 GiB (10 s)+# video_vae_decode 8.04 GiB+#+# On the Q8 path H3's memory requirement is therefore set by a SEVEN-SECOND+# phase at the start of a twenty-minute render, not by the render. The cause is+# `ddalcu-q8/text_encoder.safetensors` — 26.28 GB, a ~23B-parameter LLM that is+# already 88% 8-bit (439 quantized tensors, 23.13 GB) with only 3.15 GB left+# dense. There is no easy win inside the file.+#+# The win is not loading it. The runner has always accepted `--prompt-cache`:+# a read-through .npz of the prompt embedding, with NO draft-only restriction+# (unlike `--draft-cache-dir`, which the runner refuses outside `--draft-decode+# tae`). The panel never passed it, so every H3 render re-encoded the same+# prompt from a 26 GB model — paying both the peak and the seconds.+#+# KEYING. The runner validates the cache against the prompt AND the first-frame+# key, and RAISES on a mismatch rather than rendering the wrong thing. Its own+# first-frame key is the PATH STRING, so a file edited in place would pass its+# check while carrying different pixels. This key includes the first frame's+# size and mtime as well, which is strictly finer: a changed file lands on a+# different cache entry and re-encodes, instead of hitting a stale embedding.+H3_PROMPT_CACHE_KEEP = 40+++def h3_prompt_cache_dir() -> Path:+ return STATE_DIR / "h3_prompt_cache"+++def h3_prompt_cache_path(prompt: str, first_frame) -> Path | None:+ """Cache file for this (prompt, first frame), or None if it cannot be keyed.++ Returns None for an empty prompt: the chained shot-list path drives windows+ from `--chain-prompts` and passes no positional prompt, and the runner+ already disables the cache for every window after the first.+ """+ if not (prompt or "").strip():+ return None+ ff_key = ""+ if first_frame:+ ff = Path(str(first_frame))+ ff_key = str(ff)+ try:+ st = ff.stat()+ ff_key = f"{ff}|{st.st_size}|{int(st.st_mtime)}"+ except OSError:+ # An unreadable first frame is not a reason to fail the render; it+ # only means this key is the path alone, exactly like the runner's.+ pass+ digest = hashlib.sha256(+ (prompt + "\x00" + ff_key).encode("utf-8")).hexdigest()[:32]+ path = h3_prompt_cache_dir() / f"{digest}.npz"+ # A POISONED ENTRY WOULD BE PERMANENT. `np.savez_compressed` writes to the+ # destination directly, so a render stopped mid-write (the /stop button, a+ # crash, a full disk) leaves a truncated file — and the runner's loader+ # would then raise on THAT prompt for every future render, with no way for+ # the user to know why one prompt had stopped working. An .npz is a zip, so+ # a torn one is cheap to spot and cheaper to throw away: the only cost of+ # deleting it is re-encoding once, which is what happened before the cache+ # existed anyway.+ if path.exists() and not zipfile.is_zipfile(path):+ try:+ path.unlink()+ except OSError:+ return None+ return path+++def h3_prune_prompt_cache(keep: int = H3_PROMPT_CACHE_KEEP) -> int:+ """Drop the oldest entries. Embeddings are megabytes, not gigabytes, but an+ unbounded cache in the user's state dir is a slow leak either way."""+ d = h3_prompt_cache_dir()+ if not d.is_dir():+ return 0+ files = sorted(d.glob("*.npz"), key=lambda f: f.stat().st_mtime, reverse=True)+ dropped = 0+ for f in files[keep:]:+ try:+ f.unlink()+ dropped += 1+ except OSError:+ pass+ return dropped++def h3_paths() -> dict:"""Resolve every H3 component. Never raises — reports what's missing sothe UI can render an honest install card instead of a stack trace."""@@ -9161,7 +9314,26 @@ def h3_dit_choice() -> tuple[str, Path | None]:return "bf16", Noneif pref == "q8" and q8 is None:pref = "auto" # fall through, surfaced via /status- if SYSTEM_RAM_GB < H3_MIN_RAM_GB and q8 is not None:+ # AUTO NOW MEANS Q8 WHEREVER IT EXISTS, not just on small Macs.+ #+ # Until 2026-08-29 a 64 GB machine was handed the bf16 master because "its+ # peak fits". It does fit, and it also leaves nothing behind it: measured on+ # one prompt and seed at 640x384/73f,+ #+ # bf16 dit_load 38.56 GiB denoise peak 38.89 GiB 196.9 s+ # q8 dit_load 20.22 GiB denoise peak 21.38 GiB 200.1 s+ #+ # 45% less memory for 1.6% more time. The campaign note that priced Q8 at+ # "~12% slower" was seven times too pessimistic, and that number is why the+ # heavy default went unquestioned for so long.+ #+ # The owner watched H3 sit at ~50 GB, asked for the memory back, and graded+ # the pair himself: "b look fine they are slightly different but quality is+ # good." Faces are his metric, so that grade is the authority here — not the+ # fact that bf16 technically fits.+ #+ # `h3_dit: bf16` still forces the master for anyone who wants it.+ if q8 is not None:return "q8", q8return "bf16", None@@ -10394,6 +10566,69 @@ def h3_supports_chain_prompts() -> bool:return _h3_runner_has_flag("--chain-prompts")+def h3_supports_memory_limits() -> bool:+ """Whether the INSTALLED runner accepts `--memory-gb` / `--wired-gb`."""+ return (_h3_runner_has_flag("--memory-gb")+ and _h3_runner_has_flag("--wired-gb"))+++def h3_memory_budget(total_ram_gb: float | None = None) -> tuple[float, float]:+ """(memory_gb, wired_gb) for THIS Mac, leaving the user room to keep using it.++ THE BUG THIS FIXES. The runner's defaults are `--wired-gb 50` and+ `--memory-gb 58`, and it clamps them with++ memory_bytes = min(memory_gb * GiB, device.memory_size - 1 GiB)++ so on ANY Mac below 59 GB the 58 never binds and the clamp does: MLX is+ allowed everything except ONE gigabyte. Measured across the sizes people+ actually own:++ 32 GB Mac -> limit 31.0 GB, 1.0 GB left for the user+ 36 GB Mac -> limit 35.0 GB, 1.0 GB left+ 48 GB Mac -> limit 47.0 GB, 1.0 GB left+ 64 GB Mac -> limit 58.0 GB, 6.0 GB left (the dev machine, where it was tuned)++ One gigabyte is not enough to keep a browser open, which is exactly the+ owner's complaint: "when it's tight, you cannot use your Mac, so this is+ bad." The defaults were shaped by the machine they were written on.++ This costs no render speed and changes no output, because H3 does not need+ the memory it was being handed: the measured Q8 peak is 25.63 GiB and bf16+ is 42.17 GiB. The smallest Mac we serve H3 on (the 46 GB Q8 floor, i.e. a+ 48 GB machine) keeps 42 GB of budget against a 25.63 GiB peak — a limit+ that was never the binding constraint, standing in front of headroom that+ was.++ Headroom is the larger of 6 GB and an eighth of RAM: a fixed number starves+ a big machine of nothing and a proportional one leaves a small machine too+ little, so take whichever is kinder.+ """+ ram = float(total_ram_gb if total_ram_gb is not None else SYSTEM_RAM_GB)+ if ram <= 0:+ return (0.0, 0.0)+ headroom = max(6.0, ram / 8.0)+ memory_gb = max(8.0, ram - headroom)+ # Wired memory cannot be paged out at all, so it gets a wider margin than+ # the overall limit. The runner clamps this again to the device's own+ # max_recommended_working_set_size, which is the real ceiling.+ wired_gb = max(4.0, memory_gb - max(4.0, ram / 16.0))+ return (round(memory_gb, 1), round(wired_gb, 1))+++def h3_supports_prompt_cache() -> bool:+ """Whether the INSTALLED runner accepts `--prompt-cache`.++ Same discipline as --chain-prompts / --draft-decode: PROBE, never assume.+ The flag is present on `codex/h3-engine-v2` (the branch install_h3.js+ clones, verified 2026-08-29 at scripts/generate_staged.py:831), but a pack+ cloned before it renders perfectly well and would die on an argparse error+ thirty seconds in. Without the cache such a user simply re-encodes the+ prompt, which is exactly what every user did until today.+ """+ return _h3_runner_has_flag("--prompt-cache")++def h3_supports_tae_draft() -> bool:"""Whether the INSTALLED runner accepts `--draft-decode` (TAE fast decode).@@ -20632,6 +20867,24 @@ def run_h3_job_inner(job: dict) -> None:cmd += ["--chain-prompts", str(chain_prompts_path)]if first_frame is not None:cmd += ["--first-frame", str(first_frame)]+ # Skip the 26 GB text encoder when this exact prompt+first-frame has been+ # encoded before. On the Q8 path that phase IS the run peak (25.71 GiB vs+ # 21.28-24.68 GiB for denoise), so a hit lowers the ceiling as well as+ # saving the 7-8 s. On bf16 the ceiling stays the DiT and only the seconds+ # come back. Read-through: the runner writes the entry on a miss.+ if h3_supports_memory_limits():+ _mem_gb, _wired_gb = h3_memory_budget()+ if _mem_gb > 0:+ cmd += ["--memory-gb", str(_mem_gb), "--wired-gb", str(_wired_gb)]+ _pc = h3_prompt_cache_path(prompt, first_frame) if h3_supports_prompt_cache() else None+ if _pc is not None:+ # Prune BEFORE the render, so the entry this run is about to write is+ # never the one evicted.+ try:+ h3_prune_prompt_cache()+ except Exception: # noqa: BLE001+ pass+ cmd += ["--prompt-cache", str(_pc)]# ---- Fast draft decode (TAE) --------------------------------------------# H3's video decoder is a 36-layer ViT and it is the single largest FIXED# cost in a render: 88 s of a 501 s clip, 77% of everything that is not@@ -21114,7 +21367,8 @@ def run_job_inner(job: dict) -> None:"hardware_tier",f"Extend isn't supported on the {SYSTEM_CAPS['label']} hardware "f"tier — the dev transformer needs more headroom than this Mac "- f"has. Bump to 64+ GB or render the longer clip in one shot."+ f"has. It works from {min_ram_gb_for('allows_extend') or 48} GB "+ f"— or render the longer clip in one shot.")# Y1.036 — Extend always loads the Q8 `transformer-dev.safetensors`# weights (CFG-guided dev transformer, not the 8-step distilled).@@ -21754,7 +22008,7 @@ def run_job_inner(job: dict) -> None:f"FFLF (keyframe interpolation) isn't supported on the "f"{SYSTEM_CAPS['label']} hardware tier — Q8 + the dev "f"transformer's two-stage memory peak doesn't fit. "- f"Bump to 64+ GB."+ f"It works from {min_ram_gb_for('allows_keyframe') or 48} GB.")# Check the SAME file list the menu + /status report on. The old# "directory exists and non-empty" check let half-downloaded Q8@@ -22300,7 +22554,8 @@ def run_job_inner(job: dict) -> None:f"High quality (Q8 two-stage) isn't supported on the "f"{SYSTEM_CAPS['label']} hardware tier — Q8 dev transformer "f"(~19 GB) plus the upscaler stage doesn't fit. "- f"Use Standard or Quick instead, or upgrade to 64+ GB."+ f"Use Standard or Quick instead — High works from "+ f"{min_ram_gb_for('allows_q8') or 48} GB.")# Route to TwoStageHQPipeline (Q8 dev model + res_2s sampler + CFG anchor + TeaCache).# Defaults from ltx-2-mlx CLAUDE.md LTX_2_3_PARAMS.@@ -44606,6 +44861,29 @@ HTML = r"""<!doctype html><option value="off">Off</option></select></div>+ <!-- H3 DiT. The setting has been honoured by `h3_dit_choice()` and+ validated by the settings handler since it was added, and its own+ docstring says "`h3_dit` in Settings" — but no control was ever+ built, so the only way to reach it was a hand-written POST. The+ owner watched H3 sit at ~50 GB and asked why we could not reduce it;+ the answer was a setting he could not see. Numbers here are measured,+ not estimated (640x384/73f, seed 424242, same-seed A/B). -->+ <div class="settings-row" style="margin-top:10px" id="settingsH3DitRow" hidden>+ <label>Hailuo H3 model</label>+ <select id="settingsH3Dit" style="flex:1">+ <option value="auto">Automatic — best quality this Mac can hold</option>+ <option value="bf16">Full (bf16) — 42 GiB peak</option>+ <option value="q8">Compact (Q8) — 21 GiB peak, half the memory</option>+ </select>+ </div>+ <div class="hint" id="settingsH3DitHint" style="margin-top:6px" hidden>+ Measured on the same prompt and seed: <b>Full 38.9 GiB</b> peak in 196.9 s+ versus <b>Compact 21.4 GiB</b> in 200.1 s — <b>45 % less memory for 1.6 %+ more time</b>. Automatic gives a 64 GB Mac the full model and anything+ smaller the compact one. Choose Compact if you want to keep using the Mac+ while it renders; the memory it gives back is memory H3 was holding, not+ memory it needed.+ </div><div class="hint" style="margin-top:6px">Never changes the result — the clip is byte-for-byte the same either way.Costs a fraction of the render: about 0.2 % on High, a few per cent on a@@ -57020,6 +57298,18 @@ async function openSettingsModal() {lpSelect.value = (cur.live_preview === 'off') ? 'off' : 'on';renderMemoryPolicyHint();}+ // H3 model. Hidden entirely when H3 is not installed — an install that+ // cannot render H3 has no use for a control that only changes how it does.+ const ditRow = document.getElementById('settingsH3DitRow');+ const ditHint = document.getElementById('settingsH3DitHint');+ const ditSelect = document.getElementById('settingsH3Dit');+ if (ditRow && ditSelect) {+ const haveH3 = !!(LAST_STATUS && LAST_STATUS.h3 && LAST_STATUS.h3.available);+ ditRow.hidden = !haveH3;+ if (ditHint) ditHint.hidden = !haveH3;+ const v = String(cur.h3_dit || 'auto').toLowerCase();+ ditSelect.value = ['auto', 'bf16', 'q8'].includes(v) ? v : 'auto';+ }// Token rows. We never receive the actual key from the server (the// /settings GET returns has_X booleans only), so we display either@@ -57419,6 +57709,8 @@ async function applySettings() {}fd.set('memory_policy', document.getElementById('settingsMemoryPolicy')?.value || 'auto');fd.set('live_preview', document.getElementById('settingsLivePreview')?.value || 'on');+ const _dit = document.getElementById('settingsH3Dit')?.value;+ if (_dit) fd.set('h3_dit', _dit);// Tokens — only send a key when the input has a value. Empty input// means "leave as-is" (clearing is explicit via the Clear button).// This protects against accidentally wiping a saved key by clickingdiff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex 375279b..ebb888a 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -129,6 +129,75 @@ def _log_memory_pressure() -> None:pass+# =============================================================================+# PER-PHASE MLX MEMORY — the number that decides whether a render fits+# =============================================================================+#+# WHY THIS EXISTS+# ---------------+# `_log_memory_pressure()` above measures the whole MACHINE via vm_stat. That+# answers "is this Mac under pressure", which is not the same question as+# "which part of OUR render is the spike". H3's staged runner has printed a+# per-phase peak since the port, and that is exactly why its memory questions+# get answered in minutes; LTX had no equivalent, so the 2026-08 allocator-cache+# win (a third of peak, free) was found by a global A/B rather than by looking+# at a profile. 38.8% of the fleet renders below 48 GB, where the peak phase is+# the difference between a finished clip and a swap storm — those users deserve+# a log line that names the phase, and so do we.+#+# Peak is RESET at each phase boundary so every line is that phase's own high+# water mark rather than a running maximum that only ever reports the worst+# phase. The run maximum is tracked separately and emitted once at the end.++_MLX_RUN_PEAK_GIB = 0.0+++def _mlx_mem_reset_run() -> None:+ """Start a fresh per-run memory profile."""+ global _MLX_RUN_PEAK_GIB+ _MLX_RUN_PEAK_GIB = 0.0+ try:+ import mlx.core as mx # noqa: PLC0415+ mx.reset_peak_memory()+ except Exception: # noqa: BLE001+ pass+++def _mlx_phase_mem(label: str) -> float | None:+ """Log this phase's MLX peak, then reset so the next phase stands alone.++ Returns the phase peak in GiB, or None when MLX cannot be queried (an old+ library, or a build without the memory API) — callers treat it as optional+ telemetry and never branch on it.+ """+ global _MLX_RUN_PEAK_GIB+ try:+ import mlx.core as mx # noqa: PLC0415+ gib = 1024.0 ** 3+ peak = mx.get_peak_memory() / gib+ active = mx.get_active_memory() / gib+ cache = mx.get_cache_memory() / gib+ except Exception: # noqa: BLE001+ return None+ if peak > _MLX_RUN_PEAK_GIB:+ _MLX_RUN_PEAK_GIB = peak+ emit({"event": "log",+ "line": f"[mlx] {label}: peak {peak:.2f} GiB · active {active:.2f} · cache {cache:.2f}"})+ try:+ mx.reset_peak_memory()+ except Exception: # noqa: BLE001+ pass+ return peak+++def _mlx_mem_summary() -> float:+ """Emit the whole run's peak — the one number a Compact Mac cares about."""+ if _MLX_RUN_PEAK_GIB > 0:+ emit({"event": "log",+ "line": f"[mlx] run peak {_MLX_RUN_PEAK_GIB:.2f} GiB"})+ return _MLX_RUN_PEAK_GIB++def _aggressive_cleanup_before_generate() -> None:"""Minimize Metal heap fragmentation before pipeline generation."""try:@@ -2595,6 +2664,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()# Granular breadcrumbs so a silent helper death is traceable:# if the panel's last log line is "step:get_pipe" then we died# during pipeline init (likely OOM or weight-load issue). If@@ -2621,6 +2691,12 @@ for line in sys.__stdin__:model_dir=p.get("model_dir"))emit({"event": "log", "line": "step:get_pipe done"})_log_memory_pressure()+ # NOT "weights": measured on a live 4.7.0 render, this reads+ # 0.00 GiB because `get_pipe` is lazy — the pack is faulted in+ # during generate, so its residency lands in the denoise figure.+ # Labelling it "weights" would have every reader conclude the+ # model is free.+ _mlx_phase_mem("pipeline init")accel_mode = configure_acceleration(p.get("accel", "off"))negative_prompt = _clean_text(p.get("negative_prompt"))effective_prompt = _prompt_with_soft_negative(p["prompt"], negative_prompt)@@ -2716,6 +2792,7 @@ for line in sys.__stdin__:# Step 1: generate latents (no save)video_latent, audio_latent = _generate_latents(pipe, needs_image=needs_image, kwargs=kwargs)emit({"event": "log", "line": "step:generate done"})+ _mlx_phase_mem("denoise")# Free DiT + text encoder before the upscale + VAE decode peak.emit({"event": "log", "line": "step:free_generation_modules start"})_free_pipe_for_decode(pipe)@@ -2724,6 +2801,7 @@ for line in sys.__stdin__:emit({"event": "log", "line": "step:latent_upscale_x2 start"})video_latent = _model_upscale_video_latent(pipe, video_latent)emit({"event": "log", "line": f"step:latent_upscale_x2 done — latent {video_latent.shape[-2]}×{video_latent.shape[-1]}"})+ _mlx_phase_mem("latent upscale")# Free the upscaler before VAE decode (can be ~2-3 GB peak)._free_upscaler()# Step 3: VAE decode + save (decoder loads inside _decode_and_save_video).@@ -2734,11 +2812,14 @@ for line in sys.__stdin__:# panel's wait_done while MLX tears down ~10 GB of Metal# buffers + lazy graph nodes synchronously.emit({"event": "log", "line": "step:decode_and_save done"})+ _mlx_phase_mem("decode+save")+ _mlx_mem_summary()_aggressive_cleanup_before_generate()if not use_model_upscale:emit({"event": "log", "line": f"step:generate mode={mode} {kwargs['width']}x{kwargs['height']} {kwargs['num_frames']}f @{kwargs['frame_rate']:.1f}fps steps={kwargs['num_steps']} accel={accel_mode}"})video_latent, audio_latent = _generate_latents(pipe, needs_image=needs_image, kwargs=kwargs)emit({"event": "log", "line": "step:generate done"})+ _mlx_phase_mem("denoise")emit({"event": "log", "line": "step:free_generation_modules start"})_free_pipe_for_decode(pipe)emit({"event": "log", "line": "step:free_generation_modules done"})@@ -2757,6 +2838,8 @@ for line in sys.__stdin__:# FIX 2026-05-14: upstream renamed fps= → frame_rate= (keyword-only).out_path = pipe._decode_and_save_video(video_latent, audio_latent, kwargs["output_path"], frame_rate=kwargs["frame_rate"])emit({"event": "log", "line": "step:decode_and_save done"})+ _mlx_phase_mem("decode+save")+ _mlx_mem_summary()elapsed = round(time.time() - t0, 2)_last_activity = time.time()done_event = {@@ -2833,6 +2916,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")# Extend supports LoRAs via the same _pending_loras hook;# the dev transformer picks them up at load time just like T2V/I2V.@@ -2938,6 +3022,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")# LoRAs flow through the same wire shape as t2v/i2v. HQ is the# only path where dev-base character LoRAs actually transfer@@ -3131,6 +3216,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")num_frames = int(p["frames"])@@ -3248,6 +3334,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")audio_path = p.get("audio_path") or ""if not audio_path:@@ -3356,6 +3443,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")audio_path = p.get("audio_path") or ""if not audio_path:@@ -3442,6 +3530,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")from ltx_pipelines_mlx.hdr_ic_lora import HDRICLoraPipelineloras = p.get("loras") or []@@ -3554,6 +3643,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()configure_acceleration("off")from ltx_pipelines_mlx.ic_lora import ICLoraPipelineloras = p.get("loras") or []@@ -3707,6 +3797,7 @@ for line in sys.__stdin__:_is_busy = Truetry:t0 = time.time()+ _mlx_mem_reset_run()lm = get_gemma_lm()# Build augmented system prompt: official + Phosphene addendum.base_sys = (lm.default_gemma_t2v_system_prompt if mode == "t2v"diff --git a/test_h3_dit_setting.py b/test_h3_dit_setting.pynew file mode 100644index 0000000..22bbc5e--- /dev/null+++ b/test_h3_dit_setting.py@@ -0,0 +1,127 @@+#!/usr/bin/env python3+"""The H3 model choice existed for months with no way to reach it.++`h3_dit_choice()` has always honoured a `h3_dit` setting, `update_settings()`+has always validated it (auto|bf16|q8), and the docstring says in as many words+"`h3_dit` in Settings overrides both ways". There was no control in Settings.+It was reachable only by hand-writing a POST.++That mattered on 2026-08-29: the owner watched H3 sit at ~50 GB and asked why+we could not reduce it. The answer was a setting he could not see — Automatic+gives a 64 GB Mac the bf16 master (38.9 GiB peak) when the Q8 pack renders the+same shot at 21.4 GiB, 45% less memory for 1.6% more time, measured same-seed.++It was ALSO write-only: `update_settings` stored it but `get_settings_public()`+never returned it, so any control would have opened showing "auto" regardless+of what was saved. Both halves are covered here.+"""+from __future__ import annotations++import os+import re+import sys+import tempfile+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+os.environ["LTX_STATE_DIR"] = str(Path(tempfile.mkdtemp(prefix="phos-dit-")))+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"+os.environ.setdefault("LTX_PORT", "8307")+sys.path.insert(0, str(ROOT))++import mlx_ltx_panel as P # noqa: E402++SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")+++class TheSettingRoundTrips(unittest.TestCase):++ def test_the_ui_can_read_the_current_value(self):+ self.assertIn("h3_dit", P.get_settings_public())++ def test_a_saved_choice_comes_back(self):+ for want in ("q8", "bf16", "auto"):+ with self.subTest(want=want):+ P.update_settings({"h3_dit": want})+ self.assertEqual(P.get_settings_public()["h3_dit"], want)++ def test_junk_is_refused_with_the_valid_values_named(self):+ _, err = P.update_settings({"h3_dit": "tiny"})+ self.assertIsNotNone(err)+ for v in ("auto", "bf16", "q8"):+ self.assertIn(v, err)++ def test_the_choice_actually_reaches_the_dit_picker(self):+ P.update_settings({"h3_dit": "bf16"})+ kind, _ = P.h3_dit_choice()+ self.assertEqual(kind, "bf16")+++class AutoPrefersTheLightModel(unittest.TestCase):+ """Owner graded the pair 2026-08-29: "b look fine ... quality is good."++ Before that, `auto` gave any Mac with 60 GB+ the bf16 master, so the machine+ with the most memory was the one that spent the most: 38.89 GiB peak versus+ 21.38 GiB for the same shot at the same seed.+ """++ def test_auto_picks_q8_whenever_the_pack_is_present(self):+ P.update_settings({"h3_dit": "auto"})+ real = P._h3_q8_dit_dir+ try:+ P._h3_q8_dit_dir = lambda: Path("/tmp/pretend-q8")+ kind, path = P.h3_dit_choice()+ self.assertEqual(kind, "q8")+ self.assertIsNotNone(path)+ finally:+ P._h3_q8_dit_dir = real++ def test_auto_falls_back_to_bf16_when_q8_is_absent(self):+ P.update_settings({"h3_dit": "auto"})+ real = P._h3_q8_dit_dir+ try:+ P._h3_q8_dit_dir = lambda: None+ self.assertEqual(P.h3_dit_choice()[0], "bf16")+ finally:+ P._h3_q8_dit_dir = real++ def test_bf16_can_still_be_forced(self):+ P.update_settings({"h3_dit": "bf16"})+ real = P._h3_q8_dit_dir+ try:+ P._h3_q8_dit_dir = lambda: Path("/tmp/pretend-q8")+ self.assertEqual(P.h3_dit_choice()[0], "bf16")+ finally:+ P._h3_q8_dit_dir = real+ P.update_settings({"h3_dit": "auto"})+++class TheControlExists(unittest.TestCase):+ """The whole defect was a capability with no surface."""++ def test_there_is_a_select_with_all_three_values(self):+ self.assertIn('id="settingsH3Dit"', SRC)+ block = SRC[SRC.index('id="settingsH3Dit"'):][:900]+ for v in ('value="auto"', 'value="bf16"', 'value="q8"'):+ self.assertIn(v, block)++ def test_the_control_is_populated_and_saved(self):+ self.assertIn("ditSelect.value =", SRC, "the control never shows the saved value")+ self.assertIn("fd.set('h3_dit', _dit)", SRC, "the control never saves")++ def test_it_reads_a_status_global_that_exists(self):+ m = re.search(r"const haveH3 = !!\((\w+) &&", SRC)+ self.assertIsNotNone(m, "the H3-installed check is gone")+ self.assertIn(f"let {m.group(1)} = null;", SRC,+ f"{m.group(1)} is not a declared global")++ def test_the_memory_numbers_shown_are_the_measured_ones(self):+ block = SRC[SRC.index('id="settingsH3DitHint"'):][:900]+ for n in ("38.9", "21.4", "45"):+ self.assertIn(n, block, f"the measured figure {n} is not shown")+++if __name__ == "__main__":+ unittest.main()diff --git a/test_h3_memory_budget.py b/test_h3_memory_budget.pynew file mode 100644index 0000000..086429f--- /dev/null+++ b/test_h3_memory_budget.py@@ -0,0 +1,128 @@+#!/usr/bin/env python3+"""H3 was leaving the user one gigabyte of their own Mac.++The runner defaults to `--wired-gb 50` / `--memory-gb 58` and clamps with++ memory_bytes = min(memory_gb * GiB, device.memory_size - 1 GiB)++so on any Mac below 59 GB the 58 never binds and the clamp does — MLX is+allowed everything except ONE gigabyte. Measured:++ 32 GB -> 31.0 GB limit, 1.0 GB left 48 GB -> 47.0 GB limit, 1.0 GB left+ 36 GB -> 35.0 GB limit, 1.0 GB left 64 GB -> 58.0 GB limit, 6.0 GB left++64 GB is the machine the defaults were written on, which is why nobody saw it.+The owner's words: "even if it is tight, when it's tight, you cannot use your+Mac, so this is bad."++It costs nothing to fix, because H3 never needed that memory: measured peak is+25.63 GiB on Q8 and 42.17 GiB on bf16. The limit was standing in front of+headroom without ever being the binding constraint.+"""+from __future__ import annotations++import os+import sys+import tempfile+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+os.environ["LTX_STATE_DIR"] = str(Path(tempfile.mkdtemp(prefix="phos-h3-mem-")))+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"+os.environ.setdefault("LTX_PORT", "8305")+sys.path.insert(0, str(ROOT))++import mlx_ltx_panel as P # noqa: E402++PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")++# Measured 2026-08-29 on the staged runner, 640x384 73f and 768x416 243f.+H3_PEAK_Q8_GIB = 25.63+H3_PEAK_BF16_GIB = 42.17+++class EveryMacKeepsUsableHeadroom(unittest.TestCase):++ def test_no_machine_is_left_with_the_old_one_gigabyte(self):+ for ram in (32, 36, 48, 64, 96, 128, 256):+ with self.subTest(ram=ram):+ mem, _ = P.h3_memory_budget(ram)+ self.assertGreaterEqual(+ ram - mem, 6.0,+ f"a {ram} GB Mac keeps only {ram - mem:.1f} GB")++ def test_headroom_grows_with_the_machine(self):+ small = 32 - P.h3_memory_budget(32)[0]+ big = 128 - P.h3_memory_budget(128)[0]+ self.assertGreater(big, small)++ def test_wired_is_below_the_overall_limit(self):+ """Wired memory cannot be paged out, so it must be the tighter of the+ two or the limit is meaningless."""+ for ram in (32, 48, 64, 128):+ mem, wired = P.h3_memory_budget(ram)+ with self.subTest(ram=ram):+ self.assertLess(wired, mem)++ def test_the_budget_still_clears_h3s_measured_peak(self):+ """Headroom must not be bought by making renders fail. The smallest Mac+ we serve H3 on is the 46 GB Q8 floor, i.e. a 48 GB machine."""+ mem48, _ = P.h3_memory_budget(48)+ self.assertGreater(mem48, H3_PEAK_Q8_GIB + 4)+ mem64, _ = P.h3_memory_budget(64)+ self.assertGreater(mem64, H3_PEAK_BF16_GIB + 4)++ def test_unknown_ram_disables_the_override(self):+ """Better the runner's own defaults than a number computed from zero."""+ self.assertEqual(P.h3_memory_budget(0), (0.0, 0.0))+ self.assertEqual(P.h3_memory_budget(-1), (0.0, 0.0))++ def test_a_tiny_machine_still_gets_a_sane_floor(self):+ mem, wired = P.h3_memory_budget(8)+ self.assertGreaterEqual(mem, 8.0)+ self.assertGreaterEqual(wired, 4.0)+++class TheQ8FloorMatchesTheMeasurement(unittest.TestCase):+ """The floor must follow the peak, not a guard band round a marketing number."""++ def test_the_floor_clears_the_measured_peak_plus_real_headroom(self):+ floor = P.H3_MIN_RAM_GB_Q8+ peak_gb = H3_PEAK_Q8_GIB * (1024 ** 3) / (1000 ** 3) # GiB -> GB+ mem, _ = P.h3_memory_budget(floor)+ self.assertGreater(+ mem, peak_gb,+ f"a {floor} GB Mac is offered H3 but its budget ({mem} GB) is "+ f"below the measured peak ({peak_gb:.1f} GB)")+ self.assertGreaterEqual(floor - mem, 6.0, "no headroom left for the user")++ def test_the_floor_is_not_set_below_what_was_demonstrated(self):+ """32 GB ran in SIMULATION only, on a 64 GB machine with a flag. That+ is not evidence a real 32 GB Mac survives, so the floor stays above it."""+ self.assertGreater(P.H3_MIN_RAM_GB_Q8, 32.0)++ def test_q8_floor_is_below_the_bf16_floor(self):+ self.assertLess(P.H3_MIN_RAM_GB_Q8, P.H3_MIN_RAM_GB)+++class ItIsProbedAndWired(unittest.TestCase):++ def test_the_probe_asks_for_both_flags(self):+ import inspect+ src = inspect.getsource(P.h3_supports_memory_limits)+ self.assertIn('_h3_runner_has_flag("--memory-gb")', src)+ self.assertIn('_h3_runner_has_flag("--wired-gb")', src)++ def test_the_argv_passes_both_and_is_gated(self):+ self.assertIn('cmd += ["--memory-gb", str(_mem_gb), "--wired-gb", str(_wired_gb)]',+ PANEL_SRC)+ self.assertIn("if h3_supports_memory_limits():", PANEL_SRC)++ def test_a_zero_budget_passes_nothing(self):+ self.assertIn("if _mem_gb > 0:", PANEL_SRC)+++if __name__ == "__main__":+ unittest.main()diff --git a/test_h3_prompt_cache.py b/test_h3_prompt_cache.pynew file mode 100644index 0000000..a0af2fb--- /dev/null+++ b/test_h3_prompt_cache.py@@ -0,0 +1,201 @@+#!/usr/bin/env python3+"""H3's memory ceiling is a 7-second phase, and this is the switch that skips it.++MEASURED 2026-08-29 (staged-runner phase peaks, identical across every arm):++ text_encode_q8 25.71 GiB <- the RUN PEAK on the Q8 path+ dit_load 20.22 GiB (Q8) / 38.56 GiB (bf16)+ joint_denoise 21.28 GiB (5 s) / 24.68 GiB (10 s)++So on Q8, what a Mac must fit to run H3 at all is decided by loading a 26.28 GB+text encoder for seven seconds — not by the twenty-minute render. The encoder is+already 88% 8-bit, so there is nothing cheap left inside the file; the win is+not loading it.++`--prompt-cache` has always been in the runner and the panel never passed it.+This suite pins that it is passed, and pins the KEY, because the runner RAISES+on a cache built for a different prompt or first frame — a key that is too+coarse turns a silent cache hit into a failed render.+"""+from __future__ import annotations++import os+import sys+import tempfile+import time+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+STATE = Path(tempfile.mkdtemp(prefix="phos-h3-pc-"))+os.environ["LTX_STATE_DIR"] = str(STATE)+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"+os.environ.setdefault("LTX_PORT", "8301")+sys.path.insert(0, str(ROOT))++import mlx_ltx_panel as P # noqa: E402++PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")+++class TheKeyIsFineEnoughToBeSafe(unittest.TestCase):++ def test_same_prompt_same_frame_is_the_same_entry(self):+ a = P.h3_prompt_cache_path("a marble bust", None)+ b = P.h3_prompt_cache_path("a marble bust", None)+ self.assertEqual(a, b)+ self.assertTrue(str(a).endswith(".npz"))++ def test_different_prompt_is_a_different_entry(self):+ self.assertNotEqual(P.h3_prompt_cache_path("bust", None),+ P.h3_prompt_cache_path("bust ", None))+ self.assertNotEqual(P.h3_prompt_cache_path("a", None),+ P.h3_prompt_cache_path("b", None))++ def test_a_first_frame_changes_the_entry(self):+ with tempfile.TemporaryDirectory() as d:+ f = Path(d) / "ff.png"+ f.write_bytes(b"x" * 100)+ self.assertNotEqual(P.h3_prompt_cache_path("p", None),+ P.h3_prompt_cache_path("p", f))++ def test_editing_the_first_frame_in_place_changes_the_entry(self):+ """The runner keys on the PATH alone, so an edited file would pass its+ own check while carrying different pixels. Ours must not."""+ with tempfile.TemporaryDirectory() as d:+ f = Path(d) / "ff.png"+ f.write_bytes(b"x" * 100)+ before = P.h3_prompt_cache_path("p", f)+ time.sleep(1.1) # mtime has 1 s resolution+ f.write_bytes(b"y" * 250) # same path, different content+ after = P.h3_prompt_cache_path("p", f)+ self.assertNotEqual(before, after)++ def test_missing_first_frame_still_yields_a_key(self):+ """An unreadable frame must not take the render down."""+ got = P.h3_prompt_cache_path("p", Path("/nope/does/not/exist.png"))+ self.assertIsNotNone(got)++ def test_empty_prompt_disables_the_cache(self):+ """The chained shot-list path passes no positional prompt, and the+ runner disables the cache for every window after the first anyway."""+ self.assertIsNone(P.h3_prompt_cache_path("", None))+ self.assertIsNone(P.h3_prompt_cache_path(" ", None))+ self.assertIsNone(P.h3_prompt_cache_path(None, None))+++class APoisonedEntryIsThrownAwayNotInherited(unittest.TestCase):+ """`np.savez_compressed` writes straight to the destination, so a render+ stopped mid-write leaves a truncated .npz — and the runner's loader would+ then raise on THAT prompt forever, with nothing telling the user why one+ prompt had quietly stopped working."""++ def test_a_truncated_entry_is_deleted(self):+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)+ path = P.h3_prompt_cache_path("poison me", None)+ path.write_bytes(b"PK\x03\x04 truncated mid-write") # torn zip+ again = P.h3_prompt_cache_path("poison me", None)+ self.assertEqual(again, path)+ self.assertFalse(path.exists(), "the torn entry survived")++ def test_a_valid_entry_is_left_alone(self):+ import zipfile as _z+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)+ path = P.h3_prompt_cache_path("keep me", None)+ with _z.ZipFile(path, "w") as z:+ z.writestr("embeds.npy", b"\x00" * 32)+ self.assertTrue(_z.is_zipfile(path))+ again = P.h3_prompt_cache_path("keep me", None)+ self.assertEqual(again, path)+ self.assertTrue(path.exists(), "a good entry was deleted")++ def test_an_empty_file_counts_as_torn(self):+ d = P.h3_prompt_cache_dir(); d.mkdir(parents=True, exist_ok=True)+ path = P.h3_prompt_cache_path("zero bytes", None)+ path.write_bytes(b"")+ P.h3_prompt_cache_path("zero bytes", None)+ self.assertFalse(path.exists())+++class ThePruneIsBounded(unittest.TestCase):++ def test_prune_keeps_the_newest_and_drops_the_rest(self):+ d = P.h3_prompt_cache_dir()+ d.mkdir(parents=True, exist_ok=True)+ for f in d.glob("*.npz"):+ f.unlink()+ made = []+ for i in range(8):+ f = d / f"{i:032x}.npz"+ f.write_bytes(b"0")+ os.utime(f, (1000 + i, 1000 + i))+ made.append(f)+ dropped = P.h3_prune_prompt_cache(keep=3)+ left = sorted(x.name for x in d.glob("*.npz"))+ self.assertEqual(dropped, 5)+ self.assertEqual(len(left), 3)+ self.assertEqual(left, sorted(x.name for x in made[-3:]))++ def test_prune_on_an_absent_dir_is_a_no_op(self):+ import shutil+ shutil.rmtree(P.h3_prompt_cache_dir(), ignore_errors=True)+ self.assertEqual(P.h3_prune_prompt_cache(), 0)+++class AnOlderRunnerMustNotBeHandedAFlagItCannotParse(unittest.TestCase):+ """The bug this closes: `--prompt-cache` was passed unconditionally.++ A pack cloned before the flag existed renders every tier correctly and+ would have died on an argparse error thirty seconds into a render. The+ panel already probes for --chain-prompts, --draft-decode and+ --live-preview for exactly this reason; the cache must use the same gate.+ """++ def test_the_probe_exists_and_asks_for_the_right_flag(self):+ self.assertTrue(hasattr(P, "h3_supports_prompt_cache"))+ import inspect+ src = inspect.getsource(P.h3_supports_prompt_cache)+ self.assertIn('_h3_runner_has_flag("--prompt-cache")', src)++ def test_the_argv_is_gated_on_the_probe(self):+ line = next(ln for ln in PANEL_SRC.splitlines()+ if "_pc = h3_prompt_cache_path(" in ln)+ self.assertIn("h3_supports_prompt_cache()", line,+ "the cache path is computed without probing the runner")++ def test_no_probe_means_no_flag(self):+ real = P.h3_supports_prompt_cache+ try:+ P.h3_supports_prompt_cache = lambda: False+ self.assertFalse(P.h3_supports_prompt_cache())+ finally:+ P.h3_supports_prompt_cache = real+++class ItIsActuallyWiredIntoTheRender(unittest.TestCase):++ def test_the_argv_passes_prompt_cache(self):+ self.assertIn('cmd += ["--prompt-cache", str(_pc)]', PANEL_SRC,+ "the H3 argv no longer passes --prompt-cache")++ def test_it_prunes_before_writing_not_after(self):+ i_prune = PANEL_SRC.index("h3_prune_prompt_cache()")+ i_pass = PANEL_SRC.index('cmd += ["--prompt-cache"')+ self.assertLess(i_prune, i_pass,+ "prune must run before the entry this render writes")++ def test_draft_cache_dir_is_never_passed_to_the_runner(self):+ """`--draft-cache-dir` is refused by the runner outside --draft-decode+ tae, so passing it on a delivery render would hard-fail. Prose may name+ it (the comment explains why we chose the other one); an argv line may+ not."""+ offenders = [ln.strip() for ln in PANEL_SRC.splitlines()+ if "--draft-cache-dir" in ln+ and not ln.lstrip().startswith("#")]+ self.assertEqual(offenders, [],+ "--draft-cache-dir reached the runner argv")+++if __name__ == "__main__":+ unittest.main()diff --git a/test_mlx_phase_memory.py b/test_mlx_phase_memory.pynew file mode 100644index 0000000..c4af459--- /dev/null+++ b/test_mlx_phase_memory.py@@ -0,0 +1,172 @@+"""Per-phase MLX memory reporting — the profile a Compact Mac renders against.++`_log_memory_pressure()` measures the whole MACHINE (vm_stat). That is a+different question from "which phase of OUR render is the spike", and only the+second one tells you what to fix. H3's staged runner has printed a per-phase+peak since the port; LTX printed nothing, which is why the allocator-cache win+was found by a global A/B instead of by reading a profile.++38.8% of the fleet boots under 48 GB. For those machines the PEAK PHASE decides+whether a clip finishes or the Mac swaps, so these lines are a user-facing+diagnostic as much as an internal one.++Like `test_mlx_cache_policy`, the functions are pulled out of the real helper+with `ast` rather than imported — the helper's module body ends in a blocking+stdin read, so importing it would hang. Extraction RAISES if a function is+renamed, so this cannot rot into testing a copy.+"""++import ast+import sys+import types+import unittest+from pathlib import Path++HELPER = Path(__file__).with_name("mlx_warm_helper.py")+GIB = 1024 ** 3++_WANTED = ("_mlx_mem_reset_run", "_mlx_phase_mem", "_mlx_mem_summary")+_WANTED_CONST = "_MLX_RUN_PEAK_GIB"+++def _load(fake_mlx):+ """Exec the three real functions with a fake `emit` and a fake mlx.core."""+ tree = ast.parse(HELPER.read_text())+ picked, seen_fns, seen_const = [], set(), False+ for node in tree.body:+ if isinstance(node, ast.Assign):+ if {t.id for t in node.targets if isinstance(t, ast.Name)} & {_WANTED_CONST}:+ picked.append(node)+ seen_const = True+ elif isinstance(node, ast.FunctionDef) and node.name in _WANTED:+ picked.append(node)+ seen_fns.add(node.name)+ missing = set(_WANTED) - seen_fns+ if missing or not seen_const:+ raise AssertionError(+ f"helper no longer defines {sorted(missing) or _WANTED_CONST} — "+ "the memory profile was renamed or removed, not merely edited")++ logged = []+ ns = {"emit": lambda msg: logged.append(msg)}+ # The functions do `import mlx.core as mx` at call time, so a fake package+ # in sys.modules is enough and no real MLX is needed to run this suite.+ pkg = types.ModuleType("mlx"); pkg.core = fake_mlx+ saved = {k: sys.modules.get(k) for k in ("mlx", "mlx.core")}+ sys.modules["mlx"], sys.modules["mlx.core"] = pkg, fake_mlx+ try:+ exec(compile(ast.Module(body=picked, type_ignores=[]), str(HELPER), "exec"), ns)+ ns["_run"] = lambda: None+ return ns, logged, saved+ except BaseException:+ for k, v in saved.items():+ if v is None: sys.modules.pop(k, None)+ else: sys.modules[k] = v+ raise+++def _fake_mlx(peaks, active=1.0, cache=0.5, broken=False):+ """A stand-in that hands out `peaks` (GiB) one call at a time."""+ m = types.ModuleType("mlx.core")+ seq = list(peaks)+ m.resets = 0+ if not broken:+ m.get_peak_memory = lambda: (seq.pop(0) if seq else 0.0) * GIB+ m.get_active_memory = lambda: active * GIB+ m.get_cache_memory = lambda: cache * GIB+ def _reset():+ m.resets += 1+ m.reset_peak_memory = _reset+ return m+++class PhaseMemory(unittest.TestCase):++ def _restore(self, saved):+ for k, v in saved.items():+ if v is None: sys.modules.pop(k, None)+ else: sys.modules[k] = v++ def test_each_phase_reports_its_own_peak_and_resets(self):+ fake = _fake_mlx([4.0, 11.5, 6.25])+ ns, logged, saved = _load(fake)+ try:+ ns["_mlx_mem_reset_run"]()+ self.assertEqual(ns["_mlx_phase_mem"]("weights"), 4.0)+ self.assertEqual(ns["_mlx_phase_mem"]("denoise"), 11.5)+ self.assertEqual(ns["_mlx_phase_mem"]("decode+save"), 6.25)+ lines = [m["line"] for m in logged]+ self.assertIn("[mlx] weights: peak 4.00 GiB", lines[0])+ self.assertIn("[mlx] denoise: peak 11.50 GiB", lines[1])+ self.assertIn("[mlx] decode+save: peak 6.25 GiB", lines[2])+ # A reset after every phase is what makes each line that phase's+ # OWN high-water mark instead of a running maximum.+ self.assertGreaterEqual(fake.resets, 3)+ finally:+ self._restore(saved)++ def test_run_summary_is_the_max_phase_not_the_last(self):+ """The decode phase is smaller than denoise; the run peak is denoise."""+ fake = _fake_mlx([4.0, 11.5, 6.25])+ ns, logged, saved = _load(fake)+ try:+ ns["_mlx_mem_reset_run"]()+ for label in ("weights", "denoise", "decode+save"):+ ns["_mlx_phase_mem"](label)+ self.assertEqual(ns["_mlx_mem_summary"](), 11.5)+ self.assertIn("[mlx] run peak 11.50 GiB", logged[-1]["line"])+ finally:+ self._restore(saved)++ def test_reset_run_clears_the_previous_jobs_peak(self):+ """Job N's spike must not be reported as job N+1's."""+ fake = _fake_mlx([30.0, 2.0])+ ns, logged, saved = _load(fake)+ try:+ ns["_mlx_mem_reset_run"]()+ ns["_mlx_phase_mem"]("huge job")+ self.assertEqual(ns["_mlx_mem_summary"](), 30.0)+ ns["_mlx_mem_reset_run"]() # next job starts here+ ns["_mlx_phase_mem"]("small job")+ self.assertEqual(ns["_mlx_mem_summary"](), 2.0)+ finally:+ self._restore(saved)++ def test_missing_mlx_memory_api_is_silent_not_fatal(self):+ """Telemetry may never take a render down on an older library."""+ ns, logged, saved = _load(_fake_mlx([], broken=True))+ try:+ ns["_mlx_mem_reset_run"]()+ self.assertIsNone(ns["_mlx_phase_mem"]("weights"))+ self.assertEqual(logged, [])+ self.assertEqual(ns["_mlx_mem_summary"](), 0.0)+ finally:+ self._restore(saved)++ def test_summary_is_silent_when_nothing_was_measured(self):+ ns, logged, saved = _load(_fake_mlx([]))+ try:+ ns["_mlx_mem_reset_run"]()+ self.assertEqual(ns["_mlx_mem_summary"](), 0.0)+ self.assertEqual([m for m in logged if "run peak" in m["line"]], [])+ finally:+ self._restore(saved)+++class WiredIntoTheRenderPath(unittest.TestCase):+ """The probes are useless if they are defined but never called."""++ def test_every_phase_boundary_calls_the_probe(self):+ src = HELPER.read_text()+ for call, least in (('_mlx_mem_reset_run()', 1),+ ('_mlx_phase_mem("pipeline init")', 1),+ ('_mlx_phase_mem("denoise")', 2),+ ('_mlx_phase_mem("decode+save")', 2),+ ('_mlx_mem_summary()', 2)):+ self.assertGreaterEqual(+ src.count(call), least,+ f"{call} is no longer wired into the render path")+++if __name__ == "__main__":+ unittest.main()diff --git a/test_refusal_gates.py b/test_refusal_gates.pyindex 43e6f08..b1dafdf 100644--- a/test_refusal_gates.py+++ b/test_refusal_gates.py@@ -297,8 +297,15 @@ class TestH3RamRefusalStatesTheRealFloor(unittest.TestCase):return P.h3_ram_verdict()def test_the_two_floors_are_the_ones_the_product_believes(self):+ # The Q8 floor moved 46 -> 36 on 2026-08-29, when the full phase profile+ # replaced the single "27.3 GiB" figure it had been guessed from and the+ # panel started leaving the user real headroom. The bf16 floor is+ # unchanged. These are asserted as ORDER and RELATION, not as literals:+ # pinning the number is what made this test fail for a correct change,+ # and a stale literal here is the same defect the class exists to catch.self.assertEqual(P.H3_MIN_RAM_GB, 60.0)- self.assertEqual(P.H3_MIN_RAM_GB_Q8, 46.0)+ self.assertLess(P.H3_MIN_RAM_GB_Q8, P.H3_MIN_RAM_GB)+ self.assertGreater(P.H3_MIN_RAM_GB_Q8, 32.0)def test_a_big_mac_is_not_blocked(self):v = self._band(64.0, False)@@ -318,12 +325,13 @@ class TestH3RamRefusalStatesTheRealFloor(unittest.TestCase):self.assertIn("runs on this Mac", v["message"])self.assertIn("Install Hailuo H3", v["message"])- def test_a_small_mac_is_told_46_not_64(self):+ def test_a_small_mac_is_told_the_real_floor_not_64(self):+ """The message must quote the floor the code actually gates on."""v = self._band(32.0, False)self.assertIsNone(v["lane"])self.assertTrue(v["blocked"])self.assertFalse(v["needs_q8_dit"])- self.assertIn("46", v["message"])+ self.assertIn(str(int(P.H3_MIN_RAM_GB_Q8)), v["message"])self.assertNotIn("about 64", v["message"])self.assertIn("LTX", v["message"])diff --git a/test_tier_ram_advice.py b/test_tier_ram_advice.pynew file mode 100644index 0000000..2a3d2a5--- /dev/null+++ b/test_tier_ram_advice.py@@ -0,0 +1,131 @@+#!/usr/bin/env python3+"""The RAM number a refusal quotes must be the one the gate actually uses.++REPORTED (@fiction, Pinokio, 2026-08-29): "the high720P Q8 is not clickable,+could you solve this?" — the chip is disabled on purpose below the Q8 tier,+so the honest answer is the reason text. Reading it is what found the real+bug: four refusals told the user to "bump to 64+ GB" for High, Extend, FFLF+and the HQ chip, and all four are `allows_*` flags the table grants on+`standard`, whose floor is 48 GB. The tier modal a few clicks away already+said "48-79 GB ... Every video mode works", so the app contradicted itself and+the losing sentence cost 16 GB of hardware to act on.++`test_refusal_gates` records that this same High refusal was 23 events across+6 people in one 14-day fleet read, so the text is not hypothetical: people+reach it, and some of them will go buy a Mac because of it.++The fix derives the number from CAPABILITIES + TIER_MIN_RAM_GB. This suite+pins the derivation AND scans the shipped strings, because the failure mode+was never a wrong function — it was prose drifting away from a correct gate.+"""+from __future__ import annotations++import os+import re+import sys+import tempfile+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+STATE = Path(tempfile.mkdtemp(prefix="phos-tier-ram-"))+os.environ["LTX_STATE_DIR"] = str(STATE)+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"+os.environ.setdefault("LTX_PORT", "8298")+sys.path.insert(0, str(ROOT))++import mlx_ltx_panel as P # noqa: E402++PANEL_SRC = (ROOT / "mlx_ltx_panel.py").read_text(encoding="utf-8")+++class TheFloorTableIsTheOneSourceOfTruth(unittest.TestCase):++ def test_detect_tier_gates_on_the_published_floors(self):+ """A boundary the table names must be the boundary the gate uses."""+ for tier, floor in P.TIER_MIN_RAM_GB.items():+ if floor == 0:+ continue+ self.assertEqual(+ P._detect_tier.__globals__["TIER_MIN_RAM_GB"][tier], floor)+ # Exercised at the edges, since off-by-one here mis-tiers real Macs.+ cases = [(47.9, "base"), (48.0, "standard"), (79.9, "standard"),+ (80.0, "high"), (119.9, "high"), (128.0, "pro")]+ for gb, expected in cases:+ with self.subTest(gb=gb):+ old = P.SYSTEM_RAM_GB+ try:+ P.SYSTEM_RAM_GB = gb+ self.assertEqual(P._detect_tier(), expected)+ finally:+ P.SYSTEM_RAM_GB = old++ def test_the_big_three_are_available_from_48(self):+ """High / FFLF / Extend all unlock on `standard`, not on 64 GB."""+ for cap in ("allows_q8", "allows_keyframe", "allows_extend"):+ with self.subTest(cap=cap):+ self.assertEqual(P.min_ram_gb_for(cap), 48)++ def test_unknown_capability_returns_none_not_a_number(self):+ """Better no number than a confidently wrong one."""+ self.assertIsNone(P.min_ram_gb_for("allows_a_thing_that_does_not_exist"))++ def test_derivation_follows_the_table_if_the_table_moves(self):+ real = P.CAPABILITIES+ try:+ P.CAPABILITIES = {+ "base": dict(real["base"], allows_q8=False),+ "standard": dict(real["standard"], allows_q8=False),+ "high": dict(real["high"], allows_q8=True),+ }+ self.assertEqual(P.min_ram_gb_for("allows_q8"), 80)+ finally:+ P.CAPABILITIES = real+++class NoRefusalQuotesAHardcodedRamNumber(unittest.TestCase):+ """The regression was prose, so the prose is what gets scanned."""++ # H3 is the one honest 64: H3_MIN_RAM_GB is 60, so a 64 GB machine really+ # is the floor. Its lines are allowed to say so.+ _H3_OK = re.compile(r"h3|hailuo|~75 GB", re.IGNORECASE)++ def test_no_ltx_capability_message_hardcodes_a_ram_figure(self):+ """Scan ADVICE only.++ The tier table's own `ram_label`/blurb legitimately name GB — they are+ the source the advice should be derived FROM. What must never be+ hardcoded is the imperative: "bump to N", "upgrade to N", "needs N".+ """+ advice = re.compile(r"(bump to|upgrade to|needs \d+\+? GB"+ r"|requires \d+\+? GB)", re.IGNORECASE)+ offenders = []+ for i, line in enumerate(PANEL_SRC.splitlines(), 1):+ stripped = line.lstrip()+ if stripped.startswith(("#", "*", "//")):+ continue # commentary may cite history+ if not advice.search(line):+ continue+ if self._H3_OK.search(line):+ continue # H3's 64 is real+ if "min_ram_gb_for" in line:+ continue # derived: exactly right+ offenders.append(f"{i}: {stripped[:110]}")+ self.assertEqual(+ offenders, [],+ "these tell the user a RAM number the tier table does not own — "+ "derive it with min_ram_gb_for() instead:\n "+ + "\n ".join(offenders))++ def test_the_four_fixed_sites_derive_their_number(self):+ """Pin the specific sites @fiction's report exposed."""+ self.assertGreaterEqual(+ PANEL_SRC.count("min_ram_gb_for('allows_q8')"), 2,+ "the High chip reason and the HQ refusal must both derive it")+ for cap in ("allows_extend", "allows_keyframe"):+ self.assertIn(f"min_ram_gb_for('{cap}')", PANEL_SRC)+++if __name__ == "__main__":+ unittest.main()