favlo 0.3.0__tar.gz

favlo-0.3.0/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "favlo": {
+      "type": "http",
+      "url": "http://127.0.0.1:8129/mcp"
+    }
+  }
+}

favlo-0.3.0/.cursor/rules/commit-precheck.mdc

@@ -0,0 +1,22 @@
+---
+description: Before a commit, check every file for personal data and disallowed content
+alwaysApply: true
+---
+
+# Commit precheck
+
+Before creating a commit, check every path the commit would add. That includes source, docs, tests, shaders, data, images, and any other file. A clean subset does not excuse an unchecked path.
+
+## Personal data
+
+Look for names, email addresses, phone numbers, account handles, home directories, hostnames, serial numbers, local network addresses, tokens, keys, passwords, and private URLs. Logs, screenshots, and sample output count.
+
+Placeholders are `~/.favlo`, `127.0.0.1`, and `example-model`. The copyright line already in the repository stays. A new name does not.
+
+When a path contains personal data, leave it out of the commit. Name the path and the kind. Do not copy the value into the commit message or the reply.
+
+## NSFW, violent, and racist content
+
+Look for sexual, erotic, nude, obscene, violent, racist, hateful, or abusive text, prompts, and images, including instructions to harm a person or an animal. A refusal policy may name the categories it refuses. A test may quote a request only to assert that the refusal leaves it out of the reply.
+
+When a path contains that content, leave it out of the commit. Name the path. Do not quote the content.

favlo-0.3.0/.cursor/rules/documentation.mdc

@@ -0,0 +1,43 @@
+---
+globs: *.md
+alwaysApply: false
+---
+# Public documentation
+
+This repository is public. Anyone can read the tree, the history, issues, and pull requests. Write docs, commits, comments, and examples as if they will stay public.
+
+A block quote is a line that starts with `>`. The author wrote those lines, including the tone and the first person. Leave a block quote unchanged. Do not rephrase it, apply the tone rules to it, or move its wording into the surrounding prose. Update a block quote only when the user explicitly asks for that quote to be changed.
+
+## No personal data
+
+Do not commit personal data or secrets. That includes names, email addresses, phone numbers, account handles, home directories, hostnames, serial numbers, local network addresses, tokens, keys, passwords, and private URLs. Logs, screenshots, and sample output follow the same rule.
+
+Use a placeholder instead: `~/.favlo`, `127.0.0.1`, `example-model`. If a secret was committed, remove it and rotate it. Deleting the file in a later commit leaves it in history.
+
+## Official base models
+
+A pipeline note names the official base model and its Hugging Face model card. A finetune, merge, or other derived checkpoint stays out of `docs/<pipeline>/`, even when this repo quantizes or serves that derived checkpoint.
+
+The directory stem in the note is the official repository name plus the weight quants, such as `Qwen3.6-35B-A3B-fp4`. The card link is the publisher's repository, such as `Qwen/Qwen3.6-35B-A3B`.
+
+## Tone and shape
+
+Use calm, neutral sentences. State what the project does and what the reader can run. Skip slogans and urgency. A measured time names the machine: an M5 Pro with 48 GB. A hostname, a home directory, a serial number, and a user name stay out.
+
+Outside a block quote, a claim by the author is in the third person. Write "the author", not "I", "me", or "my".
+
+A public README says what the project is, how to install it, one minimal command, the license, and where to report a problem. Name a pipeline only in the Pipeline table. Keep the as-built detail in linked docs such as ARCHITECTURE.md. Prefer relative links between files in the repo.
+
+## Examples
+
+Wrong: "Fixed the crash on the user's M5 at `/Users/user/Models`. Email me at user@example.com."
+
+Right: "On an M5 Pro with 48 GB the dispatch measured 15.084 ms. The server listens on `127.0.0.1:8000`. A missing checkpoint path is reported and the process exits."
+
+Wrong, outside a block quote: "I admire this work, and I recommend it before trying Favlo."
+
+Right, outside a block quote: "The author admires this work and recommends it before trying Favlo." A block quote that already says this in the first person stays as written.
+
+Wrong: "Quantize writes `models/Example-Model-Uncensored-fp4` from `ExampleOrg/Example-Model-Uncensored`."
+
+Right: "Quantize writes `models/Qwen3.6-35B-A3B-fp4`. The model card is [Qwen/Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B)."

favlo-0.3.0/.cursor/rules/embeddings-pipeline.mdc

@@ -0,0 +1,19 @@
+---
+description: How a served embedding model implements EmbeddingsPipeline.
+globs: src/favlo/embeddings_pipeline.py,src/favlo/pipeline.py,pipelines/metal41/bge_m3/**,docs/bge-m3/**,harness/language_pipeline.py,harness/embeddings_agent.py
+alwaysApply: false
+---
+
+# Embedding pipelines
+
+A served embedding model inherits `EmbeddingsPipeline` in `src/favlo/embeddings_pipeline.py`. That class extends `Pipeline`. A language model and a media pipeline do not inherit it. The class writes the OpenAI list object. It does not normalize a vector or choose a hidden size.
+
+Bind `handle_embed = Pipeline()`. `embed` returns the vector and the token count. `parse` rejects a missing or blank string with `input must be a string` and `param` `input`. A `ValueError` from `embed` is a 400 with `param` `None`. The `model` field is `selection.requested_id`, or `""` when the selection is missing. It does not read `body["model"]`.
+
+A new abstract method on `EmbeddingsPipeline` updates every served embedding subclass in that same change.
+
+The language harness posts this route. After a change to `embed` or the list object, run `uv run python -m harness.language_pipeline`. That command is in [language-pipeline.mdc](language-pipeline.mdc). `python -m harness.embeddings_agent` remains the direct check of the same six sentences.
+
+Wrong: copying the list object into the pipeline package, or catching `ValueError` around the reply builder.
+
+Right: `embed` returns `(vector, tokens)` and the class writes `usage.prompt_tokens`.

favlo-0.3.0/.cursor/rules/favlo-web.mdc

@@ -0,0 +1,35 @@
+---
+description: Favlo web UI changes need a Jest unit test and a headless Playwright script against live favlo serve.
+globs: web-spa/**
+alwaysApply: false
+---
+
+# Favlo web completion
+
+A change under `web-spa/` that alters what a person can see or do needs both of the checks below, in the same change. A change that does not alter the screen adds neither.
+
+## Unit tests
+
+Use Jest with the `jest-expo` preset and `@testing-library/react-native`. Router tests use `expo-router/testing-library` and live outside `app/`. These tests do not start `favlo serve` or a browser.
+
+```bash
+cd web-spa && npx jest <test>
+```
+
+## End-to-end
+
+Playwright simulates the person in headless Chromium. The script is a fixed sequence of clicks, typing, and keys. `favlo web` is running, and it calls a live `favlo serve`. Do not stub the model or a media tool.
+
+```bash
+cd web-spa && npx playwright test e2e/<feature>.spec.ts --project=chromium
+```
+
+The script is `web-spa/e2e/<feature>.spec.ts`. `web-spa/playwright.config.ts` sets `screenshot` to `on`.
+
+- Do not use `waitForTimeout` or a retry that ignores the failure. Wait for a selector, a response, or an event.
+- The prompt and the clicks are fixed. Assert the outcome on screen. Assert exact wording only when that wording is not model output.
+- Cover wide at 1280×800. When the feature has a narrow layout, cover 390×844 in the same script.
+- Open `http://127.0.0.1:8012`. Leave the browser on `127.0.0.1`.
+- Playwright writes a screenshot for every script, including a script that passes. The file is under `web-spa/test-results/`. Read that screenshot before treating the run as finished. Leave the screenshot uncommitted.
+
+A phase is finished only when every feature script in that phase passes, its unit tests pass, and the passing screenshot shows the outcome on screen.

favlo-0.3.0/.cursor/rules/harness.mdc

@@ -0,0 +1,17 @@
+---
+description: Keep docs/harness.md in sync when harness entry points or shared harness behavior change.
+globs: harness/**,docs/harness.md
+alwaysApply: false
+---
+
+# Harness documentation
+
+[docs/harness.md](../docs/harness.md) is the catalog of `python -m harness.*` clients and shared listener or lock rules.
+
+When you add, remove, or rename a harness module, change what a harness calls on `serve` or `POST /mcp`, change exit criteria or artifact paths, or change whether a harness takes the machine lock or uses `harness.server`, update `docs/harness.md` in the same change.
+
+Give each runnable harness its own `###` subsection under the right group (language, image, video, music, voice, media preemption, or helpers). The subsection title is a short descriptive name, not the CLI. Put the command in a fenced `bash` block immediately under the title, then the prose. Mention `pytest` or `tests/test_*` when a harness has a unit test that runs without a listener.
+
+Shared infrastructure (`harness.server`, machine lock, default chat model) stays in the opening sections; do not duplicate those paragraphs in every subsection.
+
+Follow [documentation.mdc](documentation.mdc) for tone and placeholders.

favlo-0.3.0/.cursor/rules/language-pipeline.mdc

@@ -0,0 +1,28 @@
+---
+description: How a served language model implements LanguagePipeline, and when to run the language harness.
+globs: src/favlo/pipeline.py,src/favlo/language_pipeline.py,harness/language_pipeline.py,tests/test_language_pipeline.py,pipelines/metal41/qwen36_35b_a3b/**,pipelines/metal41/qwen38_27b/**,pipelines/metal41/qwen38_flash_next/**,docs/qwen36-35b-a3b/**,docs/qwen38-27b/**,docs/qwen38-flash-next/**
+alwaysApply: false
+---
+
+# Language pipelines
+
+A served language model inherits `LanguagePipeline` in `src/favlo/language_pipeline.py`. That class extends `Pipeline`. A media pipeline does not inherit it. A failed pipeline does not. The class is the disconnect shell around one chat completion. It does not encode a prompt, sample a token, or parse a tool call.
+
+Bind `handle_chat = Pipeline()`. `complete` is the pipeline's own chat, including its sampler and its stream. `RequestClosed` subclasses `ClientClosed`.
+
+`on_open` is the work that already sits outside the try. qwen36 and qwen38-27b reset `_halted` and set `runtime._stop` there. Flash Next only calls `open_request` there. `prepare` is inside the outer try and outside the disconnect try. Only Flash Next uses it, for the tool fields and the sampler. `on_finish` keeps that pipeline's current order and always runs after `prepare`. Hooks are called directly. Do not swallow a hook exception.
+
+A new abstract method on `LanguagePipeline` updates every served language subclass in that same change. A new abstract method on `Pipeline` updates every subclass of every seam.
+
+After a change to this shell, run:
+
+```text
+uv run pytest tests/test_language_pipeline.py
+uv run python -m harness.language_pipeline
+```
+
+The harness is the one agent for the registry default chat model and `bge-m3-int8`. It does not take the machine lock. It uses one `favlo serve` on `127.0.0.1:8129`. Exit 0 means `check_embeddings` ran and every paraphrase cosine beat every cross-topic cosine. A kernel or quantize edit that leaves `complete`, the disconnect shell, and the reply alone does not run the harness.
+
+Wrong: a shared sampler in `LanguagePipeline`, or a second harness per language model.
+
+Right: `complete` raises `RequestClosed`, and the shell clears `runtime._stop`.

favlo-0.3.0/.cursor/rules/mcp-server.mdc

@@ -0,0 +1,17 @@
+---
+description: Keep MCP.md in sync when the media MCP server tools, resources, or task behavior change.
+globs: src/favlo/mcp_server.py,src/favlo/memory_mcp.py,tests/test_server.py
+alwaysApply: false
+---
+
+# MCP server documentation
+
+`MCP.md` at the repository root is the public catalog of Favlo’s `POST /mcp` tools and `favlo://` resources.
+
+When you add, remove, or rename a tool or resource, change tool parameters or defaults, change optional-task behavior, or change what generate tools return (links, inline media, task fields), update `MCP.md` in the same change.
+
+`docs/serve.md` stays the listener note: transport, queue, preemption, logging, and client wiring. Do not duplicate the full tool tables there; add or adjust a single pointer to `MCP.md` if the serve note still names tools inline.
+
+Do not document chat completion or OpenAI HTTP routes in `MCP.md`. Do not add HTTP `/v1/images`, `/v1/videos`, or `/v1/audio` routes to satisfy MCP clients.
+
+Follow [documentation.mdc](documentation.mdc) for tone and placeholders.

favlo-0.3.0/.cursor/rules/media-pipeline.mdc

@@ -0,0 +1,36 @@
+---
+description: How a served media pipeline implements MediaPipeline, and when to extend and run the preemption harness.
+globs: src/favlo/media_pipeline.py,src/favlo/pipeline_worker.py,src/favlo/pipelines.py,harness/media_pipeline.py,tests/test_media_pipeline.py,tests/test_media_pipeline_harness.py,pipelines/metal41/z_image_turbo/**,pipelines/metal41/wan22_i2v/**,pipelines/metal41/wan22_ti2v_5b/**,pipelines/metal41/ace_step_15_turbo/**,pipelines/metal41/voxcpm2/**,docs/z-image-turbo/**,docs/wan22-i2v/**,docs/wan22-ti2v-5b/**,docs/ace-step-15-turbo/**,docs/voxcpm2/**,docs/harness.md
+alwaysApply: false
+---
+
+# Media pipelines
+
+A served image, video, music, or voice pipeline inherits `MediaPipeline` in `src/favlo/media_pipeline.py`. `MediaPipeline` extends `Pipeline`. A language model, an embedding model, and a failed pipeline do not inherit `MediaPipeline`. The class is the listener seam. It does not run a forward, name stages, acquire a scheduler ticket, or free device memory.
+
+Bind `handle_<kind> = Pipeline()`. `__call__` is `handle`. The subclass implements `parse`, `generate`, and `pack`. The checkpoint type stays in the pipeline package. `ClipPaused` and `ImagePaused` subclass `MediaPaused`.
+
+`generate` calls `stop()` at a stage boundary, after the Metal command already submitted has finished. Preempt raises `MediaPaused("preempt", hold)` with the host values the next stage needs. Cancel raises `MediaPaused("cancel", None)`. Device buffers do not go in the hold. They do not survive `close`. Resume calls `generate` again with that hold and the same job id.
+
+Clear a hold with `state[key] = None`. Do not `pop` the key. The exported keys are `image_hold`, `video_hold`, `music_hold`, and `voice_hold`, the same tuple in `pipeline_worker.py` and `pipelines.py`. A new kind adds its key to both tuples in that change.
+
+`parse` or `generate` raises `MediaRequestError` for a bad body. That is a 400. Any other exception fails the job with `error` `{"message", "type"}`. `describe` copies the job keys MCP already reads (`size`, `seconds`, `response_format`). `reply.json` runs once with the job before `generate`. Call it again only when `pack` or `working` returns a different dict. A new abstract method updates every subclass in that same change. One pipeline note records that pipeline's checkpoint. Do not describe another pipeline there.
+
+## Preemption harness
+
+One agent covers every served media pipeline: `python -m harness.media_pipeline`. The order is `image`, `i2v`, `t2v`, `music`, `voice`. Names after the command run that subset in the same order, as in `python -m harness.media_pipeline i2v`. An omitted list runs every name. Do not add a second preemption agent.
+
+A new served media pipeline adds one probe in that module: a name on `_PROBES`, a body in `probes()` taken from that pipeline's `smoke.json` at the shortest length that still reaches a `stop()` check, a file `artifacts/media-preempt-<name>.*`, and a shape check in `accept`. The same change adds the package and its `docs/<pipeline>/` path to this rule's globs, and one sentence in `docs/harness.md`.
+
+Run both checks before the change is done when the edit touches `MediaPipeline`, a hold tuple, or a media pipeline's `parse`, `generate`, `pack`, pause, or job dict:
+
+```text
+uv run pytest tests/test_media_pipeline.py tests/test_media_pipeline_harness.py
+uv run python -m harness.media_pipeline
+```
+
+The pytest does not open a listener and does not take the machine lock. The harness uses one `favlo serve` on `127.0.0.1:8129` and does not take the lock. If `artifacts/pipeline-test.lock` is held by a live pid, wait. Exit 0 means every selected probe paused with `task is ongoing` and that same task finished. A kernel, shader, or quantize edit that leaves the request, the checkpoint, and the job dict alone does not run the harness.
+
+Wrong: a host matmul standing in for a missing kernel, a popped hold, or one preemption agent per pipeline.
+
+Right: `MediaPaused("preempt", hold)` after the command finishes, `state["video_hold"] = None` when the job completes, and one new row in `_PROBES`.

favlo-0.3.0/.cursor/rules/memory-management.mdc

@@ -0,0 +1,42 @@
+---
+description: Pipeline-agnostic memory ledger. Owner strings, budget, sweep, and the one knob a runtime may shrink.
+globs: **/*.py
+alwaysApply: false
+---
+
+# Memory management
+
+`src/favlo/memory.py` is the only allocator. `memory` is the process singleton. Device, residency set, and command queues stay process-owned. Heaps are per owner, kind (`resident`, `scratch`, `private`), and storage (`shared` or `private`). A pipeline does not call `newBufferWithLength` or keep a second allocator.
+
+## Owner
+
+`open_runtime` accepts `owner` and `max_memory` and forwards both. Stamp `_owner` before the first allocate:
+
+```python
+self._owner = owner or f"{stem}:{id(self)}"
+```
+
+`stem` is the flag stem (`wan22-i2v`, `z-image-turbo`). Every `allocate` and `upload` in that opening uses that string. `sweep` matches the whole string. `close` sweeps it in `finally`, including when `open` fails after a span exists. A missing record raises `FileNotFoundError` before `Gpu()`. The listener passes `mint_owner(stem)` when the signature includes `owner`, records `runtime._owner`, and sweeps that opening after `close`.
+
+## Room
+
+`budget()` is reclaimable pages plus `live` plus `pending` plus bytes whose heap was released and which the kernel has not yet reported reclaimable. `live` and `pending` are properties. Room for a new span keeps those just-released bytes:
+
+```python
+ceiling = memory.budget()
+if cap is not None:
+    ceiling = min(ceiling, cap)
+room = max(0, ceiling - memory.live - memory.pending)
+```
+
+`max_memory` is the cap: `32GiB`, `512MiB`, `g`/`m`/`gb`/`mb`, or a positive byte count. Empty means uncapped. Copy the parser into the pipeline that reads it. Read the ledger when the job starts and again at `complete`. A step does not re-read it.
+
+## Fit
+
+Weights plus the requested working set must fit in `room` before the first commit. The request keeps its resolution, frame count, and duration. Shrink the one knob that pipeline owns, down to the minimum that still runs that request. When the minimum does not fit, raise `RuntimeError` and name the request. Do not drop layers, substitute a host GEMV, or change the packed quant. 16 GB is the product floor. It is not free memory and it is not `budget()`.
+
+`release` returns a span the caller has dropped. Leave a buffer a later command or a live local still names. `sweep` waits out tracked command buffers, then frees that owner's spans and idle heaps.
+
+## Release
+
+`close` sweeps the owner. The release is done when that owner has no live span and no command still holds a freed span. `memory.wait_released` returns on that check. Pending and returning bytes stay in the budget until the kernel reports them. They do not keep the process alive, and they do not keep the next call queued. A chat preemption runs the check in the process that allocated the spans, before the handler returns. The listener stores the opening report. The daemon does not admit the next call while an allocation or a release is still open. A partial drop uses `memory.confirm_released` for the bytes that sweep freed and blocks until those pages are back.

favlo-0.3.0/.cursor/rules/metal-mappings.mdc

@@ -0,0 +1,44 @@
+---
+description: Use when designing a pipeline's Metal data plane or writing its kernels. Tensor types, matmul2d, and the E8M0 scale layout.
+alwaysApply: false
+---
+
+# Metal data planes
+
+Use a Metal 4 tensor op. The type list and `matmul2d` are [WWDC26 session 330](https://developer.apple.com/videos/play/wwdc2026/330/) and `MTLTensorDataType` on macOS 27. The scale and the element encodings are the OCP MX spec, as [REFERENCES.md](REFERENCES.md) records them. A pipeline's `kernels` command is what accepts a dispatch. Another pipeline's probe is not that acceptance.
+
+## Ops
+
+`mpp::tensor_ops::matmul2d` dequantizes a quantized right-hand tensor. The left operand is float16. The destination is float32. The descriptor sets the output tile, the K tile, and the two transpose flags so they match the stored major axis. Launch it with `execution_simdgroups<N>` and have every thread in that scope take part. Apple's sample uses four simdgroups.
+
+```metal
+constexpr auto desc = matmul2d_descriptor(
+    tile_m, tile_n, static_cast<int>(dynamic_extent),
+    transpose_left, transpose_right, false);
+matmul2d<desc, execution_simdgroups<4>> op;
+```
+
+A quantized tensor can also be dequantized into a cooperative tensor and passed back into `matmul2d` when `is_compatible_as_left_input` or `is_compatible_as_right_input` is true. Reductions are the same TensorOps set. A missing kernel stays missing. A host GEMV or a CPU matmul is not a stand-in. A language-model pipeline does not fuse a whole layer. An image, video, music, or voice pipeline may place several kernels of one generation in one command buffer and may fuse those kernels.
+
+## Planes
+
+| MSL type | Role |
+|---|---|
+| `metal_fp4_e2m1` | 4-bit float weight. Magnitudes `0, 0.5, 1, 1.5, 2, 3, 4, 6`. Sign is bit 3. Low nibble is element 0 |
+| `metal_fp8_e4m3` | 8-bit float weight or key/value. OCP E4M3FN. Largest finite value is 448. `0x7F` is NaN |
+| `metal_fp8_ue8m0` | Scale plane only. One byte covers 32 values along K. Block factors `{32, 1}` |
+| `half` | Activation, norms, biases, and any matrix that is not a quantized tensor |
+| `float` | `matmul2d` destination and a recurrent or latent state |
+
+`MTLTensorDataType` also names bfloat16, fp8 E5M2, and int and uint 2/4/8/16/32. Those stay unused until this pipeline's `kernels` command completes a dispatch of that type.
+
+One scale byte is an E8M0 exponent, bias 127. Reconstruct `value × 2^(e − 127)`. Store `e` in `0..254`. `0xFF` is not a scale. A zero block stores 0. There is no zero point. Round the power of two up so the peak fits: fp4 endpoint 6, fp8 E4M3 endpoint 448.
+
+For int4, int8, int2, fp8, and E8M0, the innermost stride is 1 and every later stride is a multiple of 128 bytes. The buffer offset is 128-byte aligned. A row's packed bytes are therefore a multiple of 128: fp4 K is a multiple of 256, fp8 K is a multiple of 128, int2 K is a multiple of 512. Extra K columns are zero codes. The scale extent is the data extent divided by `{32, 1}`. The data plane ends on a 128-byte boundary and the scale plane starts there.
+
+Pad a batch or an output extent up to the tile and drop the extra rows. A K that is not a multiple of 32 is not a scale block. Pad it to the row alignment above before the pack.
+
+```metal
+// ❌ K 144 on an fp4 tensor — 144 is not a multiple of 32, so the scale plane has no whole block
+// ✅ pad K 144 → 256, pad output rows up to tile_n, drop the extra rows
+```

favlo-0.3.0/.cursor/rules/optimization-image.mdc

@@ -0,0 +1,8 @@
+---
+description: Use when optimizing an image pipeline's generation time. Do not use for language-model prefill or decode.
+alwaysApply: false
+---
+
+# Image optimization
+
+Load [optimization-image](../skills/optimization-image/SKILL.md) and follow it. The ceiling is seconds for one generation. A shorter time is faster. The 90% test compares the printed generation time with the kernel ceiling. Do not apply this rule to a language model.

favlo-0.3.0/.cursor/rules/optimization-llm.mdc

@@ -0,0 +1,8 @@
+---
+description: Use when optimizing a language-model pipeline's prefill or decode rate. Do not use for image generation.
+alwaysApply: false
+---
+
+# Language-model optimization
+
+Load [optimization-loop](../skills/optimization-loop/SKILL.md) and follow it. The ceiling is tok/s for prefill or decode. The 90% test compares the coding agent's printed rate on that phase with the kernel ceiling. Do not run the file agent. Do not apply this rule to an image pipeline.

favlo-0.3.0/.cursor/rules/pipeline-isolation.mdc

@@ -0,0 +1,67 @@
+---
+globs: *.py,*.metal
+alwaysApply: false
+---
+# Pipeline isolation
+
+Edit one runtime. Leave every other runtime's files untouched. Pipeline tests share one machine lock so several agents can edit different pipelines at the same time and only one of them runs on the GPU.
+
+`favlo serve` is the entry point for inference. The client selects one model through the OpenAI endpoints: `GET /v1/models` lists the registry, and the `model` field on `POST /v1/chat/completions` loads that row's pipeline. Quantize and the other non-serve commands require `favlo --<pipeline>`. A new runtime keeps that flag.
+
+The write set for a runtime is its entry file (`pipelines/metal41/<pipeline>.py`, which sets `PIPELINE` to that stem), its package beside that file, `docs/<pipeline>/`, and tests that import only that package. Flash Next's note is `docs/qwen38-flash-next/`. 27B's note is `docs/qwen38-27b/`.
+
+A new runtime adds those files and one row in the runtime table in `ARCHITECTURE.md`. The command discovers the entry. Do not edit `src/favlo/cli.py` to register it.
+
+Do not edit another pipeline's package, shaders, tests, or docs. A served media pipeline inherits `MediaPipeline`. A served language model inherits `LanguagePipeline`. A served embedding model inherits `EmbeddingsPipeline`. All three extend `Pipeline` in `src/favlo/pipeline.py`. Those classes are the listener seams. They do not run a forward, name stages, or branch on the pipeline. A failed pipeline inherits none of them. Do not add a kernel that branches on the pipeline. A new abstract method on `Pipeline` updates every subclass of every seam in that same change. A new abstract method on one seam updates every subclass of that seam. A seam migration may edit every served subclass of that seam in one change. Do not change `src/favlo/` unless the task is the listener, the registry, or the console. Registration loads `sampling.py` from the pipeline that owns the row. Do not pass a sampling card into the registry.
+
+A pipeline's kernels, records, and cache are described in that pipeline's `docs/<pipeline>/` note. Synthetic `matmul2d` dtype rates are [docs/synthetic-matmul2d.md](../../docs/synthetic-matmul2d.md). Root `ARCHITECTURE.md` is the process and the write set.
+
+## Model switch
+
+One chat or media pipeline is resident. A chat or media request that names a different folder or a different pipeline closes that runtime before the next one opens. The same folder and the same pipeline stay resident. An embeddings request does not close the resident runtime. It opens its own process for that request and closes it when the request returns.
+
+`close` returns only after that pipeline's device memory is released. That includes its key/value cache, prefill workspace, decode path, command queue, and open record. A prefix flush may finish first. After `close` returns, the previous runtime holds no Metal buffer, and the next runtime is the one that allocates.
+
+Spans for one runtime share one owner string. The string is the flag stem, a colon, and `id()` of the object `open_runtime` returns, taken once when that runtime opens:
+
+```text
+qwen38-27b:4317261824
+```
+
+`allocate`, `upload`, and `sweep` use that string. A cache, a codec, or a probe in that pipeline passes the same string. `close` sweeps it. After `close` returns, that owner has no span left. A command outside `favlo serve` uses the same format for the session it opens, and that session's `close` sweeps the string before the command returns.
+
+The listener records every owner that gained a span during `open_runtime`, and `runtime._owner` when that attribute is a string. It sweeps those strings after `close`. An `open_runtime` that raises sweeps every owner that appeared during the call. `open_runtime` receives `owner` when its signature includes that parameter. A pipeline that omits the parameter keeps the `id()` string above. `mint_owner` supplies the listener's string. Its token is a process counter.
+
+## Media preemption
+
+An image, video, or music pipeline assumes a chat can set `state["preempt"]` while that pipeline holds the GPU. An embeddings request does not set `preempt` and does not close that device. Read the event at each stage boundary, after the Metal command already submitted has finished. On preempt, save the finished stage in a host checkpoint, leave the job `in_progress` with the same id, and return. `close` then releases the device so the chat's model can allocate. The listener calls the same handler again after those chats. The handler loads that checkpoint and continues the unfinished work. Cancel drops the checkpoint and does not resume.
+
+Device buffers do not survive `close`. A value the next stage needs is in the host checkpoint. Each pipeline keeps that checkpoint in its own package.
+
+## Machine lock
+
+Wait until the machine is free before a test command. That includes `pytest`, `kernels`, `quantize`, `complete`, `bf16`, `probe`, `matmul`, `python -m harness`, and `python -m harness.coding`: any command that compiles shaders, dispatches Metal, loads a checkpoint, quantizes, or starts `favlo serve`. Editing the write set does not wait. Reading another pipeline does not.
+
+The machine is busy when `artifacts/pipeline-test.lock` exists and the `pid` in it is still running. A running `favlo serve` is not itself a reason to wait. Take the lock with the smoke script. When the daemon is up and no request is open, the script closes the resident model and holds chat until release. The daemon stays up. Do not kill the server, and do not kill the process that holds the lock.
+
+```text
+uv run python -m favlo.smoke_lock acquire --pipeline <stem> --command <name>
+```
+
+Exit 0 means this shell holds the lock and the GPU is free. Exit 2 means a request is open: the lock was not taken. Wait and run acquire again. Exit 3 means another live pid holds the lock. Wait. A lock whose `pid` is gone is stale. The next acquire removes it. The `favlo serve` a test starts itself is that test's process. The wait is before the test starts.
+
+Do not create the lock file by hand. Release it when the testing stretch ends, including when the command fails:
+
+```text
+uv run python -m favlo.smoke_lock release
+```
+
+Release removes the file only when its `pid` is this shell. A chat during the hold receives 503. After release, the next chat loads a model again. The lock is one JSON object and nothing else:
+
+```json
+{"pipeline": "qwen38-27b", "pid": 12345, "command": "kernels"}
+```
+
+`pipeline` is the flag stem. `pid` is the shell that owns the test. `uv` and `python` are skipped when the script records that pid, so `uv run` names the shell that stays up for the stretch. A nested command from that shell leaves the file in place. `command` is the short name of that test. Do not write a name, home directory, hostname, or device path.
+
+The file lives under `artifacts/`, which is gitignored. Do not commit it. `pid` is the shell that ran acquire, not the short-lived Python process. Run acquire, the test, and release in that same shell.

favlo-0.3.0/.cursor/rules/public-algorithms.mdc

@@ -0,0 +1,27 @@
+---
+globs: *.py,*.metal
+alwaysApply: false
+---
+# Public algorithms, Metal mapping
+
+Every equation in a pipeline comes from a public paper, spec, or vendor document, then mapped onto a Metal op an M5 Pro with 48 GB runs. Another repository's source, tests, comments, or design notes are not a reference. Porting them pulls in that runtime's layout and hides the Metal mapping.
+
+Score a formula on this runtime's own forward. An int4 argmax is not evidence the equation is right. Check the BF16 shader dot of the checkpoint values.
+
+Record a pipeline citation in that pipeline's references note, and a process citation in REFERENCES.md. The as-built form goes in that pipeline's note, or in ARCHITECTURE.md when the change is the listener, the registry, or the console.
+
+## Memory
+
+Allocate the input path and the output path first. The input path is the key/value cache and the prefill workspace. The output path is decode. Other modules, such as the expert atlas, staging buffers, and a scratch buffer that the forward can rebuild, receive what remains.
+
+When a formula needs more device memory, leave the key/value cache, the prefill workspace, and the decode path allocated. Name another module to drop, and say which bytes that module returns.
+
+## Examples
+
+Wrong: open another runtime's n-gram forward and copy its hash so the tokens match.
+
+Right: Cheng et al. eq. (6) for the branch gate, the tech report's `1/n_r` on the residual read, and a Metal float dot of the stored matrix.
+
+Wrong: shrink the key/value cache so the atlas stays complete.
+
+Right: keep the cache, the prefill workspace, and decode, and drop atlas images that the forward can read again from the record.

favlo-0.3.0/.cursor/rules/python-file-split.mdc

@@ -0,0 +1,32 @@
+---
+description: Split and organize Python files by responsibility, with one-way imports
+globs: **/*.py
+alwaysApply: false
+---
+
+# Python file split
+
+Split a module when it has more than one job, or when a section is data the rest of the file only reads. Line count is not the trigger. PEP 8 sets no file-length limit. Related classes and functions stay in one module.
+
+A package name is an identifier. A hyphenated pipeline entry stays a path-loaded file. The package beside it uses underscores. `qwen38-flash-next.py` loads `qwen38_flash_next`.
+
+## How to cut
+
+- One module, one responsibility. Imports point one way: `formats` → `convert` / `session` → `runtime` → `commands`.
+- If two modules need each other, the cut is wrong. Move the shared names into a third module, or leave the pieces together.
+- Keep one class in one file. Do not break a class into mixins to shorten a file.
+- Move large source strings, such as Metal shaders, into files the module reads as text. Compile them the same way as before.
+- Re-export the names callers already use from the package `__init__.py`. A path-loaded entry exposes those names, including `main`.
+- Use a regular package with `__init__.py`. A namespace package is for one name split across distributions.
+- A new model is a new entry file under `pipelines/metal41/`, a new package beside it, and a `PIPELINE` assignment. It does not edit another pipeline. A served media pipeline inherits `MediaPipeline`. A served language model inherits `LanguagePipeline`. A served embedding model inherits `EmbeddingsPipeline`. A failed pipeline inherits none of them. A kernel does not branch on the pipeline.
+- Update that pipeline's `docs/<pipeline>/` note in the same change that moves one of its modules. Update root ARCHITECTURE.md only when the process contract or the runtime table changes.
+
+## Examples
+
+Wrong: split `Qwen38Runtime` into `gdn.py`, `qsa.py`, and `moe.py` that import each other.
+
+Right: leave the forward in `runtime.py`. Put packing in `formats.py`, which the runtime imports and which does not import the runtime.
+
+Wrong: name the package `qwen38-flash-next/` and import it.
+
+Right: keep `qwen38-flash-next.py` as the entry. Put the modules in `qwen38_flash_next/`, and read `shaders/act.metal` as text.

favlo-0.3.0/.cursor/rules/research-evidence.mdc

@@ -0,0 +1,43 @@
+---
+description: Bound a research claim to the measured remainder and the search that limits it
+globs: docs/**/*.md,REFERENCES.md,RESEARCH.md
+alwaysApply: false
+---
+# Research evidence
+
+A public commit records an artifact and a date. It does not establish that the idea is original. Write "not found in these sources on this date." Do not write "first," "novel," or "no prior work."
+
+Split the proposal into the method, the model or task, the measurement, and the mechanism. Name the closest public predecessor for each part, with a link and one sentence on what that work already did. Papers, model cards, and shipped code all count. The sentence this repo may own is only the remainder.
+
+A measured mapping onto one machine is a claim even when the method is already published. A measurement from this repository names that machine as an M5 Pro with 48 GB. The remainder is this implementation's table: the times, the bandwidth ceiling, or the recorded rate for that pipeline's task. Name the closest published implementation of the same task and the figure it reported. The "not found" sentence names this table. A tile or stride the vendor requires is a constraint. An unmeasured mapping stays a plan.
+
+## Citing this software
+
+[REFERENCES.md](../../REFERENCES.md) and a pipeline note cite the papers, model cards, and vendor documents the implementation uses. [RESEARCH.md](../../RESEARCH.md) indexes measured remainders. Neither file is a citation of Favlo.
+
+The citable software record is [CITATION.cff](../../CITATION.cff) at the repository root. Its version and release date are the release a reader cites. A paper that uses a recorded rate cites that software version and the predecessor papers named in the note. The note does not embed a BibTeX entry for Favlo, and the catalog does not gain a row for the software citation.
+
+A release that changes the version updates `CITATION.cff` in that same change. Do not invent a DOI or an ORCID. The repository URL is the identifier until a DOI is archived.
+
+## Where a note lives
+
+An idea with no measurement is not committed in this repository.
+
+A measured remainder is one Markdown file, `docs/<pipeline>/research/<slug>.md`. A format bound is a measurement of the code points. A per-matrix table is a measurement of the checkout. A dispatch table, a bandwidth ceiling, or a recorded rate is a measurement of this implementation. The file says which one it holds. The pipeline README links it as a measurement. The serving note changes only when that behavior ships.
+
+The root catalog is [RESEARCH.md](../../RESEARCH.md). It is an index, not a second copy of the notes. One row per claim, added in the same commit as the note. Columns are slug, pipeline, status, search date, shipped date, benchmark date, the one-sentence remainder, and the note path. Status is `measured` while the serving note is unchanged, `shipped` once that note describes the behavior, and `narrowed` after a correction is appended. A row stays. The shipped date is the date that serving note described the behavior, and it stays empty while status is `measured`. The benchmark date is the date of that pipeline's latest harness scores. It stays empty when that pipeline has no harness scores. The index does not repeat the table, the predecessors, or the command.
+
+Sections, in order: Remainder, Predecessors, Rule, Command, Table, Search, Corrections. The command is the one that regenerates the table. Corrections are appended. Earlier sections stay as committed.
+
+Ship that remainder in the same commit as the claim:
+
+- The formula, the budget or decision rule, and the command that regenerates the result.
+- The measured table. A claim with no numbers stays a plan.
+- The search note: queries, date, and the predecessors above.
+- A license and a readme so a second person can rerun it. This repo's license and readme are the package ones.
+
+The git author date is chosen by the committer. The public timestamp is the host's record of the push, or a Software Heritage snapshot of that commit. An ACM artifact badge means the artifact is available, or that another team reran it. The badge does not certify novelty.
+
+Wrong: "This is the first fp4-to-fp8 allocation by weight error."
+
+Right: "MixQuant scores layers by weight error. This note records the relative error of these feed-forward matrices under this quantizer. A search on 21 October 2026 did not find that table."

favlo-0.3.0/.cursor/rules/serving-media.mdc

@@ -0,0 +1,41 @@
+---
+description: Save generated media to disk, then return that file. Generate tools are optional MCP tasks.
+alwaysApply: false
+---
+
+# Serving media
+
+When an API returns generated media, write the file first and send that file. The kind does not matter: image, audio, video, or another download.
+
+This applies to a new endpoint and to a change in how an existing one returns bytes. A kernel, a quantizer, a CLI `--out` path, and a harness artifact stay where they are.
+
+## Tasks
+
+`generate_image`, `generate_video`, and `generate_music` are optional MCP tasks on `io.modelcontextprotocol/tasks`. A client that advertises the extension receives a task (`resultType` `task`, `pollIntervalMs` 2000). The GPU starts when the worker reaches it. Poll `tasks/get` or `media_status` until `completed`, `failed`, or `cancelled`, then `resources/read` the `favlo://` link. A client that does not advertise the extension receives the finished tool result on that same `tools/call`.
+
+Leave the mode optional. Required mode returns JSON-RPC `-32021` when the client did not advertise the extension, and the job never starts. Many MCP clients do not advertise it.
+
+The inline call ends at that client's tool timeout. An image or a short clip can finish inside it. A long video or a long music clip needs a client that polls. Otherwise the call ends at the timeout while the job is still running. Closing the poll request does not cancel the job. Cancel with `tasks/cancel` or `media_cancel`.
+
+Do not add an HTTP media route so a client can skip the extension. Chat stays `POST /v1/chat/completions`.
+
+## Order
+
+1. Save the uncompressed file under `~/.favlo/<kind>/<id>.<ext>`. Write a sibling `.tmp`, then replace the final path. The id is the job id. Refuse an id that contains a path separator, `.`, or `..`.
+2. Write the served file from that saved file. A compressed download is a second file beside it. The content response reads the served file.
+3. Stream the served file, with its media type. A missing file is 404.
+4. The job JSON names the id. It carries no filesystem path and no media bytes.
+
+Tests pass a temporary home on the request state. They do not write `~/.favlo`.
+
+A kept file expires through one integer in `~/.favlo/settings.json`. The sweep deletes a file whose age has reached that value and drops the matching job. The default for a new kind is one day when the pipeline note does not name another value.
+
+## Examples
+
+Video: save `~/.favlo/videos/<id>.avi`, encode `<id>.mp4` from that file, then `resources/read` of `favlo://videos/{id}` reads the MP4 as `video/mp4`.
+
+The same shape for a PNG or an audio clip: one directory per kind, one extension, one read of the saved file.
+
+Wrong: keep the served bytes only on the request state and send those bytes.
+
+Wrong: put `{"path": "/Users/example/clip.mp4"}` on the job.