Pay for what you enable: the name, the state of the art, and the path for YazSes¶

Date: 2026-10-21 · Status: research input to ADR-028 and to a proposed runtime-residency ADR · Author: Mohsen Seyedkazemi Ardebili · Builds on: the 2026-08-15 survey, ADR-016, ADR-018, ADR-027, ADR-028

The brief: a user who selects a few features downloads and runs only those features' libraries and models; a user who selects everything downloads more and uses more CPU and RAM. Each feature installs what it needs, automatically, as a separate step, when it is turned on.

Evidence labels: [F] a primary source says so · [S] secondary source only · [M] measured in this repository on 2026-10-21 · [O] engineering judgment · [U] not verified.

1. What the approach is called¶

Recommended naming [O]: call it "features on demand" in user documentation and "on-demand feature delivery under a pay-for-what-you-use budget" in design documents. Avoid "plug-ins". The accurate architecture term is a modular monolith with optional first-party components: one repository, one lock file, many independently installable and independently loaded parts.

The principle has four costs, and a feature should pay none of them while it is off:

1. Download (bytes fetched),
2. Disk (bytes kept),
3. RAM (bytes resident while running),
4. CPU (work and wake-ups while idle or active).

YazSes is close to the state of the art on 1 and 2. Most of the remaining work is 3 and 4.

2. How others do it, and what went wrong for them¶

The projects that succeed with this are all first-party: the vendor builds every module, each module is locked to one base build, and the base knows the catalogue. Failures cluster in open ecosystems, from two causes: installing requirement strings an extension supplies at runtime, and a shared module namespace with no global lock.

3. Python standards, status on 2026-10-21¶

Statuses were checked against the PEP index (peps.python.org/api/peps.json) on this date. [M]

4. Where YazSes stands, measured¶

Measured on origin/main fa058766 in throwaway environments (base-only install, Linux x86_64, CPython 3.12). [M]

Done, and at the state of the art:

• 22 extras plus all. The 149-row capability registry maps features to extras (system/features.py::_FEATURE_DEPS), and a test holds the pins to pyproject.toml.
• No optional extra is imported at module scope (AST scan; guards green).
• Disabled subsystems are not constructed at daemon start.
• Models download on first use.
• The marginal cost is shown before install (system/feature_sizes.json). There is an import-time budget in CI.
• The PyPI-channel install is a transaction (system/install_txn.py). It holds the base pinned as constraints, records the install where the channel keeps it (uv receipt, pipx inject), and rolls back on failure.
• Frozen Windows builds have a verified add-on-pack path (ADR-028 Phase 1, on main, not yet in a release).

Base weight:

• import yazses.cli: 63–73 ms, 18 MB RSS.
• import yazses.core.daemon: 250–310 ms, 33 MB RSS.
• Base site-packages: 451 MB. Four wheels are 85% of it: av, ctranslate2, onnxruntime, numpy, all from faster-whisper's dependency tree (the August survey's finding still holds).

Gaps (ranked by what they cost a user who did not ask for the feature):

5. The runtime half: making RAM and CPU proportional¶

The August survey and ADRs 016, 018 and 028 cover download and disk. The brief also says "more CPU and RAM when you select more". That only holds if a feature's memory and CPU also leave when it is not in use. The state of the art, in order of value [O, each with a precedent]:

1. Import nothing for a disabled feature. Already enforced.
2. Load on first use, not at start. VS Code's activation events (docs).
3. Unload after idle, per feature, with a configurable keep-alive. Ollama's default is 5 minutes (FAQ).
4. Core dictation STT should stay resident by default, because first-word latency is the product. It should still offer an opt-in idle unload for low-RAM machines.
5. Meeting diarization, gaze, TTS, the LLM and voiceprint should all have timeouts.
6. Run the heaviest features in worker processes: gaze/mediapipe, llama-cpp, torch voiceprint, diarization. They would talk to the daemon over the existing IPC. This is the VS Code extension host and Chromium's process model (Chromium).
7. Native allocators (ONNX Runtime, CTranslate2, torch) do not reliably return freed memory to the OS. A worker's exit is the only guaranteed release.
8. It is also a fault boundary: a mediapipe crash does not kill dictation.
9. It is the isolation boundary that ADR-018 names as the condition for ever reopening plug-ins: a process with no network and no injector handle.
10. A memory-bounded scheduler: at most N heavy models resident; evict the least recently used. This is Ollama's OLLAMA_MAX_LOADED_MODELS.
11. Budgets in CI, so proportionality is a test and not a hope:
12. import time (exists; tighten it);
13. "disabled features add zero modules" (sys.modules allowlist);
14. per-feature peak RSS (pytest-memray limit_memory, or a subprocess RSS probe) on a nightly job with real models;
15. idle-CPU budget: daemon CPU seconds over 60 s idle with everything off.
16. Show RAM and CPU at consent time, next to the download size: "Eye control: 220 MB download, about N MB RAM while active". This extends ADR-018 §1. The figures would come from the nightly table, the way feature_sizes.json supplies disk figures.

6. Target architecture and roadmap¶

Roadmap, smallest and safest first:

1. Quick fixes. Each is a small diff with its own test.
2. Move latency out of the RECOMMENDED tier (gap 2).
3. Drop opencv-python from the gaze extra, because mediapipe's opencv-contrib-python is a superset (gap 3).
4. Pin voiceprint on Linux to the CPU torch index (gap 7).
5. ADR-028's eight questions. Answered on 2026-10-21 (see that ADR). Two code facts from this research change Phase 1:
6. The diarization pack fails §1's DLL rule as written, because sherpa-onnx-core ships its own unsigned onnxruntime.dll (1.28.2) next to the base's Microsoft-signed 1.28.0. The build would withhold the pack.
7. Torch collides with the base's libiomp5md.dll.
8. A runtime-residency ADR (L6).
9. Idle-unload defaults per feature.
10. The out-of-process rule for gaze, LLM, voiceprint and diarization.
11. A per-feature RSS budget on a nightly job.
12. Hashed PyPI-channel installs (L2/L3).
13. Export a hashed lock covering all extras, install the feature's slice with --require-hashes --only-binary :all:, and ask y/N above a size threshold (gap 6).
14. Reclaim on disable (L7).
15. Offer to remove a disabled feature's packages, packs and models, with the size.
16. Channel-native routes.
17. Snap components instead of bundling every engine into the snap (gap 4).
18. Flatpak extensions.
19. CI install matrix.
20. none / each feature alone / all, on Linux nightly, plus the existing frozen probe per pack.

What not to do:

• Do not add third-party plug-ins (ADR-018 §3 stands).
• Do not design against PEP 771.
• Do not adopt the lazy keyword while 3.11–3.14 are supported.
• Do not use per-feature virtual environments for in-process features: they duplicate numpy and ONNX Runtime and cannot share one process. A per-feature environment is right only for a worker that needs a conflicting stack, such as torch.

Sources¶

Primary: PEP 751 · PEP 735 · PEP 771 · PEP 810 · pip secure installs · uv export · PyInstaller runtime information · Home Assistant manifest · Android Play Feature Delivery · Windows Features on Demand · MSIX optional packages · Visual Studio workloads · Blender extension wheels · VS Code extension host · Flatpak extensions · snap components · Playwright browsers · Ollama FAQ · ComfyUI dependencies · Chromium process model · pytest-memray · cppreference: zero-overhead principle

Secondary: HA forum, ResolutionImpossible · Blender #119681 · GlassWorm (The Hacker News) · ComfyUI_LLMVISION (404 Media) · Ultralytics (Wiz) · CVE-2024-39705 (Tenable) · Mozilla bug 1038317

Measurements: this repository, origin/main fa058766, base-only environments built from git archive, CPython 3.12, Linux x86_64; Windows wheels downloaded from the uv.lock URLs and checked against their lock hashes.

Not verified: TUF on PyPI; snap components' production readiness; whether Microsoft Store certification checks every inner PE file for a signature.