Prepare the next ht ↔ upstream/master reconciliation (2026-07-28)

[marksverdhai]

Objective

Prepare a deliberate reconciliation of the downstream ht feature set onto the current clean upstream mirror. This issue is the planning/audit gate; it does not authorize rewriting the default branch.

Immutable baseline

Ref	Commit	Meaning
master / upstream/master	f95de9776b5b90dd993f36d2bd66a3eee21c887f	Clean upstream mirror after the 2026-07-28 sync
ht / origin/ht	798cf6cbe56440132df23eb2318f587b16e3c00e	Current downstream tip
ht-b10156-798cf6c	798cf6cbe56440132df23eb2318f587b16e3c00e	Published immutable rollback/checkpoint tag
merge base	c299a92c38b6de6a1139617652b66081828648db (b9824)	Last common upstream commit

Current divergence: 335 master-only commits and 38 ht-only commits.

Open issue / PR disposition before cutting the candidate

There are five open issues and five open draft PRs as of this audit:

• Router co-loads same-device-pinned models and OOMs: --models-max fit decision ignores per-device VRAM #66 — router same-device co-load OOM
  • Steady-state per-device fit/eviction shipped in fix(server): implement in-router memory fit and VRAM-based eviction (#66) #136.
  • Draft fix(server): reserve per-device VRAM for LOADING models (#66) #148 covers the remaining LOADING reservation race and still needs the policy decision documented there: hard 503/retry gate vs proceed-and-risk-OOM when in-flight loads saturate a device.
  • Draft RFC: Router Admit Decision for Same-Device-Pinned Models (#66) #146 is the RFC/ADR; decide whether to update it as the shipped Approach-1 decision record or close it as superseded.
  • Decide whether fix(server): reserve per-device VRAM for LOADING models (#66) #148 lands on ht before reconstruction or is rebased/cherry-picked onto the reconciliation candidate.
• Hivemind Maintenance Tasks Epoch 1 #112 — Hivemind Maintenance Tasks Epoch 1
  • Most recorded work is complete. The remaining HPC optimization is hardware-blocked and independent of reconciliation.
  • Carry the hardware-blocked item forward or close/replace the stale epoch tracker after reconciliation.
• Rebase conflict: ht on master (2026-06-28) #147 — automated rebase-conflict report
  • This preparation issue supersedes its understated one-file scope. Keep Rebase conflict: ht on master (2026-06-28) #147 linked until the reconciliation ships, then close it with the final candidate/rollback references.
• Router: reload doesn't reconcile alias_to_name → get_meta mis-resolves removed/moved aliases (stale cache) #150 — stale alias cache on router reload
  • Draft fix fix(server): reconcile alias_to_name on reload (#150) #153 is green/mergeable per the maintenance log.
  • Land before the cut or explicitly port it into the candidate; do not silently strand it when ht moves.
• anthropic-compat: mixed tool_result+text user turn reorders tool result after text (wrong OAI ordering) #151 — mixed tool-result/text ordering
  • Draft fix fix(server): preserve tool result adjacency in compat converters #156 covers Anthropic and Gemini conversion plus regression tests.
  • Land before the cut or explicitly port it into the candidate.
• Draft Dirty sweep: preserve uncommitted work (ht-llama.cpp) #157 — dirty-sweep archive
  • Treat as preserved scratch/archeology, not reconciliation input, unless separately reviewed and intentionally selected.

All five PRs currently target the pre-reconciliation ht. Before swapping ht, each must be merged, rebased/retargeted, or explicitly closed with a preservation reference.

Fresh conflict forecast

Measured locally with git merge-tree --write-tree --name-only master ht:

• 880 paths changed upstream since the merge base.
• 781 paths changed on ht since the merge base.
• 264 paths were touched on both sides.
• Git predicts 200 conflicted paths.
• 172 conflicts are under tools/ui/.
• 28 conflicts are outside tools/ui/, concentrated in:
  • fork/CI policy: .github/workflows/build-self-hosted.yml, AGENTS.md, CONTRIBUTING.md
  • common/speculative plumbing: common/{common.cpp,common.h,speculative.cpp}, include/llama.h
  • TurboQuant/CUDA: ggml/include/ggml.h, ggml/src/ggml-cpu/arch-fallback.h, ggml/src/ggml-cuda/{fattn.cu,getrows.cu,ggml-cuda.cu}
  • DFlash/model core: src/llama-{arch,context}*, src/models/dflash.cpp
  • tests: tests/{CMakeLists.txt,test-backend-ops.cpp,test-llama-archs.cpp}
  • server/router: tools/server/{server-context*,server-http.cpp,server-models.cpp,server-task.h,server.cpp} and test_compat_oai_responses.py
  • UI embedding: scripts/ui-assets.cmake, tools/ui/embed.cpp

The tools/ui bulk must be classified against current fork policy, not resolved mechanically: this repo ships the prebuilt upstream UI bundle and retains only the embed/PWA glue needed by llama-server; product-facing SvelteKit/Tauri code belongs in heierchat and must not be reintroduced here.

Required method and safety rules

Lessons from #38 and the #147 triage remain binding:

• Build a fresh reconciliation branch from the pinned master; do not replay a naive long rebase and accept whatever compiles.
• Disable rerere for the operation. Historical cached resolutions have silently dropped HT code.
• Reconstruct and review the net downstream feature set by subsystem.
• Keep master pristine; all work belongs on a feature/integration branch.
• Do not force-push ht until the candidate is reviewed and the maintainer explicitly approves the history rewrite.
• Use --force-with-lease, pinned to the audited 798cf6cbe remote tip, if approval is given.
• Retain ht-b10156-798cf6c as the rollback anchor.

Feature-preservation audit

Use README.md's HT Fork Changes inventory as the source of truth and prove preservation or intentional retirement for each subsystem:

• TurboQuant types, CPU paths, fused CUDA kernels, D=512 FA paths, CLI type exposure, and tests
• DFlash architecture/speculative plumbing, kernels, tests, and bench harness
• Gemma4 MTP delta, checking first whether upstream has absorbed all or part of llama : add Gemma4 MTP ggml-org/llama.cpp#23398
• Router/heierchat integration, fit byte plan, per-device eviction, reload/alias behavior, proxy hardening, and checkpoint cap
• Embedding/image-input shims, Gemini compatibility, steering hints, LoRA discovery/conversion, and LCO/MLA conversion support
• termd and its isolation/network policy
• Prebuilt UI download/embed/PWA behavior without restoring out-of-tree product UI
• HT CI triggers, runner retargeting, release behavior, branding, and contribution policy
• Documentation/help output for all surviving downstream flags and cache types

For any downstream delta now present upstream, retire the duplicate intentionally and record the upstream commit/PR instead of preserving two implementations.

Validation gates

No waivers and no identifier-count-only sign-off:

• C++/ggml/server configure and build per docs/build.md; at minimum build llama-server and the affected test targets
• Run the relevant CTest/server suites, including router/fit, chat compatibility, responses, architecture, quantization, and backend-op coverage
• CUDA compile plus TurboQuant/DFlash correctness on suitable hardware
• cd tools/termd && cargo check && cargo clippy
• Build with default LLAMA_USE_PREBUILT_UI=ON; verify the downloaded UI embeds and serves
• Verify llama-server --help exposes all retained HT flags/types
• Run feature-preservation diff/audit against ht-b10156-798cf6c
• All required GitHub checks green
• Schedule a fleet canary/runtime smoke for router model load/unload/reload, chat/tool conversion, embeddings/image input, DFlash, and rollback
• Record exact candidate commit, test artifacts, canary image/build info, and rollback command before branch replacement

Proposed execution sequence

1. Resolve the open-issue/draft-PR decisions above.
2. Create a non-default integration branch from f95de9776b.
3. Reconstruct HT changes by subsystem, with focused commits and per-subsystem review.
4. Resolve the UI bulk according to the prebuilt-bundle boundary.
5. Run preservation and validation gates; fix failures without waivers.
6. Push the candidate as a non-default branch and review its full diff against master.
7. Canary and document rollback.
8. Obtain explicit maintainer approval for the destructive/default-branch step.
9. Replace ht using a lease pinned to 798cf6cbe.
10. Verify remote refs, update/close Rebase conflict: ht on master (2026-06-28) #147, and record final dispositions for every issue/PR listed here.

Completion criteria

This issue closes only when the reconciled ht is based on the pinned-or-newly-repinned clean master, every README inventory item is preserved or intentionally retired with evidence, all gates pass without waivers, open work has been carried forward deliberately, and the rollback tag remains reachable.

[marksverdhai]

Closing as a non-mergeable reconciliation prototype, superseded by #162.

Preserve archaeological head caad2af3e93d1facd73db597a6c666310d3ba8f3 for selective patch recovery only. No commit in this PR is approved wholesale.

Audit at that exact head:

• actual ancestry is master@f95de9776b5b90dd993f36d2bd66a3eee21c887f, but the PR targets ht@798cf6cbe56440132df23eb2318f587b16e3c00e;
• GitHub comparison is 347 commits, 973 files, and 197 conflicts;
• unresolved conflict markers remain in CONTRIBUTING.md;
• all 716 upstream tools/ui files are restored despite the fork's prebuilt-UI boundary;
• required HT surfaces are missing, including LocateAnything/MoonViT, llama-fit-params --fit-print-plan, TurboQuant CLI/bench/help exposure, and analytical-fit MTMD changes;
• there are no CI checks or reviews.

The clean replacement belongs in the subsystem stack recorded on #162: infra/UI policy, TurboQuant, core inference, MTMD/fit, server/API, termd, and docs/CI. This branch should not be retargeted or merged.