# DS4Server implementation plan Bundle/application identifier: `DS4Server.rfc1437.de` DS4Server is the native macOS Rust/Iced application counterpart to `../ds4`. The reference implementation remains normative: `ds4.c`/`ds4.h` define model and session behavior, `ds4_server.c` defines the HTTP API, and `ds4_agent.c` defines local-agent behavior and tools. Parity means matching observable behavior and fixtures, not merely exposing similar controls. All planned execution targets one self-contained Mac. ## Current state - The macOS application shell, projects, session rename/pin/archive/delete, SQLite transcripts, model preferences and downloads, Stats dashboard, native Application/Edit/Window menu integration, development bundle, and shared lazy model lifecycle are implemented. - DeepSeek V4 Flash runs through the Rust/Metal executor with full configured context, ratio-4 sparse attention, cold and resumed batched prefill, prefix continuation, durable KV checkpoints, cancellation, and idle unload. - The configurable localhost endpoint implements all `ds4_server.c` routes, streaming and non-streaming envelopes, model aliases, CORS, tool replay and continuation, malformed DSML recovery, transient prefix-aware KV reuse, disconnect/queue cancellation, and shared model scheduling. The full automated C/Rust differential corpus remains open. - Local sessions now match the long-running `ds4_agent.c` baseline: the full starting tool set, unlimited tool rounds, queued user guidance between tool rounds, session date/time context, periodic tool-contract reminders, cooperative Stop, and explicit activity/failure states are implemented. - Local tools are hardened for daily use: canonical project boundaries reject parent and symlink escapes, shell commands receive a deliberate environment, risky shell and visible-browser actions share one cancellable Allow once/Deny approval path, and compact tool cards expose bounded parameters, results, and parsing/approval/queue/run/completion lifecycle state without showing DSML. Background jobs and bounded output files stop and clean up with Stop, session switches, and application shutdown. - Context compaction uses the reference soft and exact token-counted hard triggers, private live-model summaries, bounded summary and tool-result retries, a recent verbatim tail, running-job observations, and compatible KV checkpoints. Every summary is a visible durable history marker carrying its tail boundary; the full chat remains scrollable, while missing or incompatible KV state rebuilds from the last marker, its tail, and later messages. Manual compact is available after new chat following the latest marker, alongside a checkpoint-discard/rebuild action. - Focused coverage exercises triggers, summary bounds and sanitizing, tail selection, queued guidance, checkpoint identity, running jobs, durable compaction markers, relaunch, and continued tool work after rebuild. - DeepSeek V4 Flash now supports DS4-compatible SSD expert streaming, legacy MTP, DSpark, and directional steering in the Rust executor. The optional modes are integrated into the same target-owned generation path used by local chat and the endpoint; disabling them preserves the resident greedy token baseline. Runtime counters feed the Stats dashboard without inference thread UI work. - Hardware-backed token oracles cover resident versus SSD execution, legacy MTP, DSpark, SSD combined with both speculative modes, directional steering, and target-only fallback. Differential endpoint scripts cover deterministic output, finish state, and usage when reference and Rust servers are supplied. - GLM 5.2 has a dedicated Rust/Metal executor and DeepSeek V4 Pro uses the generalized DeepSeek graph. Their remaining work is validation rather than catalog plumbing: GLM MTP is still rejected, the full GLM/Pro hardware matrix is incomplete, and Pro still needs explicit memory-admission verification. - The remaining model-independent execution gaps are fine-grained SSD cache telemetry, the DS4 expert-locality profiler, and resident multi-session server batching/scheduling. - The native UI is on Iced 0.14. Chat transcripts use its table-aware Markdown content and viewer path, with a regression for code-styled line-count tables produced by coding models. ## Delivery order 1. **Next:** finish the remaining DS4 execution parity: detailed SSD cache telemetry, expert profiling, resident multi-session batching, GLM MTP, and the GLM/Pro hardware matrix. 2. Product completion, exhaustive parity verification, and distribution. 3. Optional extensions: Dev Brain and A2UI. ## 1. Completed — tool hardening and safety Goal: make the existing tool set safe and clear enough for productive daily use without weakening its ability to inspect, edit, build, and test a project. - Keep file tools strictly inside the selected project after canonicalization, including symlinks and nonexistent write targets. Boundary escapes are rejected, not approved as exceptions. - Centralize tool approval. Reuse the existing visible-browser approval path for actions that require consent instead of adding tool-specific modal systems. - Require confirmation before destructive shell commands or commands that affect state outside the project, elevate privileges, launch external apps, or create unrequested network side effects. Show the exact command and working directory; support Allow once and Deny. Do not persist broad trust silently. - Define the shell environment deliberately so application credentials and unrelated secrets are not exposed accidentally. Preserve the minimum normal development environment needed for project commands. - Render streamed tool calls as compact cards with their real lifecycle: parsing, awaiting approval, queued, running, completed, failed, or stopped. Show bounded parameters and results, provide copy/open actions where useful, and never display raw DSML as ordinary assistant prose. - Keep background shell jobs cancellable and observable through app stop, session switches, compaction, and application shutdown. Retain bounded output files only as long as needed and report cleanup failures. - Continue enforcing context-aware read/search/bash result limits. Oversized output must remain available through continuation or a file reference rather than being inserted wholesale into the prompt. - Test project-boundary and symlink escapes, destructive-command approval, denial and cancellation, browser approval, output bounding, and session switching with a live job. Exit criterion: use the agent for a real inspect/edit/test cycle while every side effect is visible, risky actions require consent, Stop works at every stage, and no file tool can escape the selected project. ## 2. In progress — DS4 execution technology parity Goal: finish the model-independent Metal/runtime capabilities in `ds4.c` before adding larger model families. Every capability must be shared by local chat and the HTTP endpoint through the single process-wide model owner. ### 2.1 Implemented — SSD streaming Flash routed experts stream through the unchanged DS4 Metal kernels with automatic or explicit cache budgets, cold start, generated DS4 hotlists, preload controls, asynchronous I/O, and bounded cache eviction. Resident and SSD generation share token oracles. Engine atomics expose resident/cache bytes, requests, bytes read, and wait time; the UI samples and graphs their rates on its normal metrics thread. Native cache hit/miss, eviction, and preload-progress telemetry remains to be surfaced without changing the carried-over kernels. SSD streaming is the capacity prerequisite for larger models and therefore comes before GLM 5.2 and DeepSeek V4 Pro execution. - Keep non-routed weights resident while loading routed MoE experts from the GGUF into a bounded in-memory cache on demand. - Port DS4's automatic cache sizing from the recommended Metal working set, non-routed weights, KV/context requirements, graph scratch, and routed-prefill headroom. Preserve explicit expert-count and GiB-budget modes. - Port cold start, hot-expert preload, explicit preload count, full resident layer policy, cache eviction, and the overlapped prefill/decode loading path. - Keep inference correct under cache misses, short reads, cancellation, memory pressure, unload, and model replacement. A streaming failure must produce a bounded request error, not partial model state. - Report resident bytes, cache capacity, hit/miss and load rates, SSD bytes and latency, preload progress, and memory-pressure decisions in Stats. - First prove resident-versus-streaming token parity on DeepSeek V4 Flash. Keep the cache and I/O layer model-aware so later GLM/Pro milestones add policy and graph support rather than a second streaming subsystem. ### 2.2 Completed for Flash — legacy MTP and DSpark Both support GGUF formats are validated and executed by Rust. Draft generation, confidence/margin gates, target verification, accepted-prefix commit, rollback, strict/quality fallback, cancellation, checkpoint identity, streaming output, usage accounting, and Stats counters use the existing generation lifecycle. Sampled decoding remains target-only as in DS4. SSD streaming works with both modes, and long-chat DSpark prefill has a dedicated hardware regression. - Load and validate the optional Flash legacy-MTP or DSpark support GGUF without treating either as a standalone model. Preserve exact support-kind and target compatibility checks. - Port draft generation, confidence/margin pruning, target-model verification, accepted-prefix commit, rejected-suffix rollback/replay, cache counters, and cancellation boundaries. The target model always owns the output stream. - Honor MTP draft depth/margin and DSpark confidence/strict settings. Match the reference rules for greedy, sampled, and quality modes rather than applying speculation where DS4 falls back to target-only decode. - Match current DS4 compatibility between SSD streaming and DSpark; remove temporary Rust-only exclusions where the reference supports the combination. - Expose accepted/drafted token counts, acceptance rate, verifier cost, and effective speedup in Stats. Do not call the feature complete merely because it produces correct tokens; it must also preserve checkpoints, tools, streaming responses, usage accounting, and Stop behavior. - GLM's in-model MTP path belongs to the GLM milestone, but it should reuse the verifier/session machinery established here. ### 2.3 Mostly completed — remaining Metal execution controls Directional steering, power throttling, prefill chunking, quality mode, weight warming, and simulated memory pressure now affect execution. CPU helper-thread and expert-profile settings are rejected instead of being persisted no-ops. Porting DS4's expert-locality profile output is the remaining item here. - Port directional steering files and exact FFN/attention application, including DS4 defaults, validation, zero-scale behavior, and checkpoint/model identity effects. - Audit every accepted execution preference against the Rust executor. Power, prefill chunking, quality/exact kernels, warm weights, simulated memory, and expert profiling must either affect execution as DS4 defines or be disabled with a clear explanation; persisted no-op settings are not parity. - Add hardware-backed token/activation fixtures for each mode and keep the ordinary resident Flash path unchanged when optional features are off. ### 2.4 Remaining — single-machine server batching - Port DS4's resident multi-session batching and server scheduling only after the serialized path remains the correctness oracle. Preserve per-request cancellation, finish reasons, usage, and KV ownership while batching prefill or decode work. - Keep all scheduling, model state, KV state, and request handling within the local process. Networked execution and non-Metal backends are outside the product scope. Exit criterion: DeepSeek V4 Flash matches DS4 token output and lifecycle in resident, SSD-streamed, MTP, DSpark, steering, and batched-server configurations, with optional modes off producing the same baseline behavior as today. ## 3. Implemented executors — additional-model validation remains GLM 5.2 has a dedicated DSA/MLA executor and DeepSeek V4 Pro uses the generalized DeepSeek graph. Both are selectable runtimes, not catalog-only placeholders. They are not complete parity milestones until the remaining items below pass on the installed hardware fixtures. ### GLM 5.2 - Port the GLM DSA/MLA graph, dense-cache behavior, model-specific tensor and quantization paths, sampling defaults, reasoning controls, prompt rendering, and stop tokens. - Use the already defined GLM tool syntax through the same durable local-agent loop and expose identical behavior through every HTTP route. - Port GLM SSD streaming policy, resident full-layer selection, and the MTP block stored in the main GGUF. Respect GLM restrictions on power, prefill chunking, steering, and external support models. - Validate resident and streamed token output against DS4 fixtures before the Model Manager advertises GLM as runnable. ### DeepSeek V4 Pro - Generalize the Flash graph only where Pro's dimensions, layers, routed experts, quantization layouts, or output path actually differ. - Support resident and SSD-streamed single-machine configurations with explicit memory admission checks. Never begin a load that cannot leave room for the configured KV/context and graph working set. - Match Pro prompt, sampling, checkpoint, HTTP, and agent behavior. Preserve the reference compatibility matrix for MTP/DSpark rather than assuming Flash support artifacts work with Pro. - Validate supported single-file Q2/Q4 configurations against DS4 fixtures before advertising them as runnable. Exit criterion: each advertised model passes the same local-agent, checkpoint, HTTP, SSD-capacity, cancellation, and deterministic token-output matrix as DeepSeek V4 Flash. ## 4. Product completion and verification ### Reference parity and regression coverage - Complete the automated black-box C/Rust corpus for Models, Messages, Chat Completions, Responses, Completions, and OPTIONS in streaming and non-streaming modes. Cover aliases/defaults, malformed input, context limits, tools, reasoning, cache reuse, disconnects, queueing, CORS, errors, usage, and finish reasons. - Add every new agent/runtime/model capability to both local and endpoint regression coverage. HTTP conversations remain client-owned and may persist only opaque content-addressed KV entries, never application transcripts. - Reuse DS4 prompt, sampling, KV, server, agent, and hardware fixtures. Keep formatting, Clippy, bundle, and unit tests as commit gates; run hardware matrices only where the required GGUF and machine are available. ### macOS product and distribution - Finish the remaining native menu and text behavior: functional File/View/Help actions, dynamic enabled state, undo/redo parity, and selectable/copyable transcript text. - Finish session/model binding and recovery surfaces needed to explain why a checkpoint is reused or rebuilt. Keep archive as metadata-only and never delete project contents. - Add production signing, hardened runtime, required entitlements, notarization, update delivery, and release automation. Preserve all upstream DwarfStar/llama.cpp notices for adapted code and kernels. Exit criterion: a notarized build can be installed on a clean supported Mac, run the full local-agent and endpoint smoke matrix, restart into its previous sessions, and update without losing projects, transcripts, models, or KV data. ## 5. Optional future extensions These are not DS4 baseline parity and must not delay the milestones above. ### Dev Brain - Let the user opt into one existing Obsidian vault through a native folder picker and persist a security-scoped bookmark for sandboxed restart access. - Add one project-independent tool with bounded search, read, and create/append operations for Markdown notes. Return vault-relative citations and exclude `.obsidian`, hidden files, deletion, and arbitrary overwrite. - Reuse the existing file/search implementation with a separate explicit vault boundary. No vault means no tool and no effect on ordinary sessions. Exit criterion: store a memory in one project, restart, and retrieve it with a vault-relative citation from another project without granting broader disk access. ### A2UI local-chat surfaces - After the ordinary tool UI is stable, use `../bDS2` as the reference for typed cards, charts, forms, lists, metrics, mind maps, tables, and tabs. - Validate and persist versioned structured payloads with their messages. Render with native Iced/SVG primitives; reject model-authored HTML, JavaScript, styles, file URLs, and arbitrary commands. - Keep A2UI local-chat-only until a real endpoint client requires a compatible protocol. All mutating actions continue through the normal approval path. Exit criterion: supported surfaces render accessibly, malformed payloads fall back safely, interactions are validated, and the same surfaces rehydrate after restart.