Hebrus 0.3.0

Hebrus 0.3.0

Hebrus 0.3.0 is the first source release under the Hebrus name. It provides a
Metal-first inference engine for a deliberately small set of qualified MoE
artifacts on Apple Silicon, including bounded SSD expert streaming where the
runtime support contract admits it.

This release contains source and provenance files only. It does not contain
prebuilt engine binaries, model weights, or a Hebrus Studio application bundle.

Highlights

• Canonical hebrus, hebrus-server, hebrus-agent, hebrus-bench, and
  hebrus-eval commands; the corresponding ds4* names remain same-binary
  compatibility aliases in this release.
• Machine-readable schema-1 --capabilities=json output across all five roles.
• Staged installation with versioned Metal resources and executable-relative
  shader discovery.
• Stable Qwen3.6 MLX Affine4/group-64 support plus an explicit, nonrecommended
  Q2_K_XL Beta profile.
• Corrected Qwen resident 2–31-token routed-MoE reduction, with complete
  synthetic boundary coverage at 1, 2, 25, 31, and 32 rows.
• Deterministic, fail-closed source bundle generation and verification.

See the versioned release notes,
changelog, and
runtime support contract.

Source and provenance

• Tag target: 463eaa068d1a06142d03245955fd47299c20fa81
• hebrus-0.3.0.tar.gz: 97a6886de0d065ad156a13ea0e839dc7821120e4b3d440dbfba98967d950c00f
• hebrus-0.3.0-source.json: 77bf1ad80fdbe49559358e593b248989dd232ad0fae5ea762bd1c80606f47b2c

Download all three source assets together and verify them with:

shasum -a 256 -c SHA256SUMS

The manifest records the complete source commit, 12-character build identity,
commit timestamp, archive size, member count, and archive SHA-256.

Validation

• Exact-tag Linux and macOS CI: run 31900639931
• Exact-tag hosted source build and smoke install: run 31900789732
• Exact-tag source-bundle smoke: PASS locally, including byte-identical rebuild,
  manifest verification, staged install, aliases, and installed Metal resources.
• Local make premerge: PASS on code parent
  a202f7fb85acddd870f1e1a1a803718cfdfa1945 on Apple M5 Pro, 64 GiB,
  macOS 26.5.2 (build 25F84). The tag target differs only in the three recorded
  publication-date fields and passes the release-metadata and source-bundle gates.
• Stable Qwen Affine4 resident server gate: PASS on code parent
  a202f7fb85acddd870f1e1a1a803718cfdfa1945 on both hebrus-server and
  ds4-server; exact 25-token layer-major path; two exact
  HEBRUS ALIAS PARITY OK responses per persistent process; clean shutdown;
  evidence bundle SHA-256
  32f1ba6657daa688709a897c248737a03e0e4f1e1b67a1e1b8322408a3a645e4.
• Qwen Q2_K_XL Beta exact-artifact alias gate: PASS on the same code parent;
  artifact size 12290632032 bytes and SHA-256
  30c22f70aff0f05986b517ee4ad8fef554a1b5aab6971c9ca09f999566d30143;
  explicit resident mode exercised the 25-token short-prefill frontier through
  both hebrus-server and ds4-server, with two exact
  HEBRUS ALIAS PARITY OK responses per process and clean shutdown; report
  SHA-256 502b398ce3def2033ba090cf93ae3c74bee59bc4153d77ed2e050c39577f77b4.
• DeepSeek V4 Flash exact-artifact release smoke: SKIPPED by maintainer
  release decision. The exact 86720114272-byte artifact was not available
  locally; the available 0731 variant is 32 bytes shorter and byte-different,
  so no result from it is attributed to this release.
• GLM 5.2 exact-artifact functional smoke: PASS on the same code parent;
  artifact size 262147193504 bytes and SHA-256
  7f5017e3076e706c78f2a5322b035a9e2f6519c65ff5b6be8b2d91aeff61505d;
  AUTO resolved the qualified SSD path, completed all 288 prompt tokens and
  32 greedy decode tokens with zero swap; log SHA-256
  6a3fe1524956611520583cb7fd650de29e1cb79750bb606dbaa633437e421ee1.

No performance claim is derived from the functional alias gates. Historical
benchmark numbers remain scoped to their linked artifact, commit, hardware,
context, and runtime mode.

Current limits

• Beta, source-built software for Apple Silicon and Metal.
• Not a general GGUF runner: only exact artifacts in the support contract are admitted.
• CPU is reference/debug only; CUDA, ROCm, and distributed inference are not shipped.
• Qwen Q2_K_XL remains Beta and is not full-window qualified.
• The Qwen 24 GiB lane remains a publication candidate pending its physical sustained gate.
• The local server has no built-in authentication and should not be exposed to untrusted networks without an authenticated layer.
• hebrus-agent remains alpha.

Hebrus retains substantial implementation and history from
antirez/ds4. See
acknowledgments
and third-party notices.

Hebrus v0.2.0 — Historical DwarfStar release

DwarfStar v0.2.0

Release date: 2026-07-20

This release makes the fork's production path deliberately narrow: local
Apple Metal, at least 64 GB unified memory, and one embedded ExpertMajor v2
artifact for each qualified model family. Canonical GGUFs, sidecars,
ExpertMajor v1, distributed inference, CUDA, and ROCm are not compatibility
paths in this release.

Qualified models

Model	Normal 64 GB startup	Qualified artifact
Qwen3.6-35B-A3B	AUTO selects resident when the pressure gate passes	Qwen3.6-35B-A3B-DS4-ExpertMajor-v2-Q4_K_S.gguf
DeepSeek V4 Flash	AUTO selects resident or SSD from the live memory plan	DeepSeek-V4-Flash-IQ2XXS-w2Q2K-AProjQ8-SExpQ8-OutQ8-chat-v2-imatrix-DS4-ExpertMajor-v2.gguf
GLM 5.2	AUTO always selects the qualified SSD Gold path	GLM-5.2-DS4-ExpertMajor-v2-Q2_K.gguf

Download one exact release artifact and start it without model-admission or
cache-tuning flags:

./download_model.sh qwen-v2
./ds4 -m gguf/Qwen3.6-35B-A3B-DS4-ExpertMajor-v2-Q4_K_S.gguf \
  --ctx 8192 -p "Hello"

Use deepseek-v2 or glm-v2 for the other families. The downloader pins a
versioned model-repository release tag and verifies the complete byte size and
SHA-256 before reporting success. The same normal command shape applies to
ds4-server; residency and the safe expert-cache tier are runtime decisions.

Runtime changes

• Qwen uses the exact scalar Q8 Metal decode path. A final zero-swap 32K
  A/B/B/A preserved byte-identical evidence but found the paired-Q8 experiment
  neutral-to-worse, so its M5-only kernel and test were removed.
• DeepSeek uses a pressure-gated phase policy: 259 experts during prefill,
  4,129 through 32K decode, and 2,065 at 65K and above on the qualified 64 GB
  M5 lane. The old AUTO plan can swap at 32K; the retained path completes 32K,
  65K, and 100K with zero new swapout.
• GLM maps the exact norm/bias spans required by the compact-indexer transition.
  This fixes the former 32K failure without changing attention, KV geometry,
  RoPE, or context allocation.
• Acceptance benchmarks now require isolated 128, 2K, 8K, and 32K prompts,
  exact decode evidence, TPOT p50/p95, memory pressure, zero new swapout, and
  separate prose and security/coding lanes for routing/cache changes.
• CUDA and ROCm remain frozen with source and build targets absent. Distributed
  inference remains retired and its former flags fail closed.

M5 Pro 64 GB release evidence

Model and 32K workload	Prefill	Decode	Tail evidence
Qwen, resident prose final scalar source	65.76 t/s	about 3.18 t/s	315.193/317.518 ms p50/p95
DeepSeek, SSD prose final stack	164.43 t/s	7.27 t/s	105.410/149.943 ms p50/p95
GLM, SSD prose	44.73 t/s	1.87 t/s overall	472.624 ms p50, about 2.12 t/s steady

The DeepSeek original controls can swap, so this release does not publish a
32K speedup percentage. GLM also has no speedup percentage because the original
baseline fails before logits. Its same-prompt corrected output is identical to
the earlier gold and the final 32K run has zero swap. A separate security/coding
GLM prompt routes through more experts and measures 1.33 t/s; the difference is
workload locality, not a same-condition regression.

Full artifact identities, prompt hashes, invalid cohorts, 65K/100K DeepSeek
results, and functional API/agent/disk-KV checks are in
2026-07-20-long-context-metal-stack.md.

Upgrade boundary

There is no backward-compatibility promise for old model files. Remove old
startup flags and select a qualified v2 file explicitly. Qwen and DeepSeek may
resolve to different residency modes on different supported Macs; GLM resident
mode is rejected even on a larger host until it has its own qualification lane.

Hebrus v0.1.0 — Historical DwarfStar release

DwarfStar v0.1.0

Release date: 2026-07-17

This is the first numbered release of the andreaborio/ds4 fork. It promotes
the measured Qwen3.6-35B-A3B Metal stack and introduces the single-file
DS4-native expert-major GGUF.

What ships

• Resident Qwen prefill and decode kernels, bounded macro-prefill, expert
  grouping, I/O overlap, phase-aware cache growth, prompt lookup, and the
  pressure-aware 16 GiB planner.

• One expert-major store used by both resident Metal buffers and SSD cache
  fills.

• Automatic loading of the embedded ds4.expert_major.v1 GGUF tensor.

• A transactional converter and offline verifier:

  make ds4-qwen-pack
  ./ds4-qwen-pack native SOURCE.gguf SOURCE.experts.pack OUTPUT.gguf
  ./ds4-qwen-pack verify-native SOURCE.gguf OUTPUT.gguf

• Legacy canonical Qwen GGUF and explicit sidecar support for migration and
  A/B testing.

The release model is
Qwen3.6-35B-A3B-DS4-ExpertMajor-v1-Q4_K_S.gguf: 20,808,970,240
bytes with SHA-256
fb2b344d49f0c3dfd854cfc11d92ffc873cc93a1d30bf4664e5aea6f1bfef839.
It is only 406,816 bytes larger than its canonical input; routed weights are
stored once, not duplicated.

Format boundary

ds4.expert_major.v1 is intentionally model-specific: Qwen3.6-35B-A3B,
40 layers, 256 routed experts, Q4_K gate/up/down records. The artifact remains
a GGUF v3 container, but generic loaders cannot execute its routed weights.
They should fail on the absent canonical tensor names.

Use the canonical GGUF with llama.cpp, MLX, CUDA, ROCm, or any loader that does
not explicitly implement this extension. The native artifact is the preferred
download only for this DS4 release on Apple Metal.

Integrity and failure behavior

The converter verifies the source hash, sidecar payload hash and index, copies
all non-routed tensors and metadata byte-for-byte, reopens the store at its
embedded offset, rehashes it, fsyncs, and only then renames the output.

A missing or invalid legacy sidecar falls back to canonical tensors. An invalid
embedded store is fatal before inference: the native file contains no second
routed layout, so fallback would be semantically unsafe.

Validation gates

• Clean Metal and CPU builds.
• Model-free Qwen expert-store, expert-group, and Metal lifecycle tests.
• Native converter fixture with a non-zero embedded offset.
• Canonical versus native model-backed parity at 2K, 8K, and 16K contexts.
• A bounded M1 Pro 16 GiB SSD smoke.

The model-backed parity matrix and artifact identity are recorded in
docs/qwen-expert-major-store.md. The final native/sidecar/native publication
gate was byte-identical at 2K, 4K, 8K, and 16K; the exact commands and evidence
hashes are in docs/benchmarks/2026-07-17-qwen-native-expert-major.md.

DeepSeek and GLM

DeepSeek and GLM are not mislabeled as v1-compatible. Their expert types and
per-layer geometry can vary, so they require a generic versioned manifest plus
their own correctness and performance matrices. That work follows this release
and will retain canonical loading until each native artifact clears those
gates. The reusable format contract and independent promotion sequence are in
docs/expert-major-v2-roadmap.md.