DS4Server/PLAN.md

# 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 persist user, assistant, reasoning, and tool roles. The agent
  executes the complete `ds4_agent.c` starting tool set and reinjects the same
  model-specific tool contract when sessions are opened or continued.
- The remaining baseline gaps are long-running agent behavior and tool safety.
  SSD streaming, speculative decoding, steering, GLM 5.2 execution, and
  DeepSeek V4 Pro execution are not implemented in the Rust executor. Some
  related catalog, validation, and preference plumbing already exists but must
  not be treated as runtime support.

## Delivery order

1. **Next:** long-running agent stability and remaining `ds4_agent.c` parity.
2. Tool hardening, approvals, and productive tool presentation.
3. Remaining DS4 execution technology, starting with SSD streaming, then
   speculative decoding and the other Metal/runtime parity work.
4. Additional model execution: GLM 5.2 and DeepSeek V4 Pro.
5. Product completion, exhaustive parity verification, and distribution.
6. Optional extensions: Dev Brain and A2UI.

## 1. Next — long-running agent stability and `ds4_agent.c` parity

Goal: a local agent session must be able to run long read/edit/test loops,
cross the context limit repeatedly, survive interruption or relaunch, and
continue with the same durable task state as `ds4-agent`.

### Context compaction

- Port the reference soft trigger: compact before a user turn or tool
  continuation at 85% context use, or when at most 8192 tokens remain, with the
  free-token threshold capped to one eighth of small contexts.
- Port the hard trigger: before appending a tool result that would leave
  insufficient answer room, compact once and retry. If it still does not fit,
  return a bounded tool error that tells the model to request less output.
- Use the live model to generate an internal durable task-state summary. The
  prompt and generated summary are private compaction work, never ordinary
  user/assistant messages, and may not execute tools or retain thinking/DSML
  control markup.
- Preserve goals, constraints, files touched, commands and important results,
  decisions, known failures, and next steps. Prefer reloadable paths, ranges,
  and commands over copying bulky data into the summary.
- Rebuild the model context exactly as the reference does: current system/tool
  contract, durable summary, then a recent verbatim tail. Keep up to 10% of the
  configured context as the tail, capped at 50000 tokens, and align it to a
  user-turn boundary when possible.
- Generate at most the reference summary budget, stop at model control or tool
  markers, and never let the private compaction exchange become the reusable
  session prefix.

### Durable transition and recovery

- Treat transcript replacement and the new KV checkpoint as one logical
  transition. Persist the compacted semantic transcript and checkpoint
  metadata only after the rebuilt prefix is valid.
- On cancellation, summary failure, prefill failure, or application exit, keep
  the previous durable transcript, invalidate any KV state contaminated by the
  private compaction prompt, and make the next turn rebuild safely.
- Reopen a compacted session with the same summary and recent verbatim turns.
  If its checkpoint is absent or incompatible, rebuild it from persisted
  messages without changing the visible conversation.
- Preserve relevant live tool state across compaction. In particular, append a
  compact observation for running shell jobs so the model can still inspect or
  stop them after the context rebuild.
- Add a user-visible action equivalent to `/compact`, plus the reference
  strip/rebuild behavior: discard a session KV payload without discarding its
  transcript, then rebuild on the next use.
- Bind checkpoint compatibility to the model identity, quantization, context,
  rendered transcript, and payload ABI. A model/configuration change must
  rebuild rather than reuse an invalid prefix.

### Long-turn behavior

- Accept user input while an assistant/tool loop is active. Queue it visibly
  and inject it after the current tool result, before the next assistant
  continuation, matching `ds4_agent.c` instead of starting a competing turn.
- Preserve the reference rule that there is no arbitrary maximum tool-round
  count. Completion, Stop, context pressure, or a real error ends the loop.
- Match the reference date/time context injection and periodic system/tool
  prompt reminder so long or reopened sessions do not drift away from the tool
  contract.
- Keep Stop cooperative across summarization, compacted-prefix prefill,
  generation, and active tool work. A stop must always leave a transcript that
  can be reopened.

### Presentation and verification

- Show explicit `Compacting`, rebuilding/prefill, queued-input, stopped, and
  failed states without blocking the Iced event loop. Keep the compacted
  summary inspectable without presenting the private prompt as user history.
- Add focused tests for soft and hard triggers, tail selection, tool-result
  retry, cancellation rollback, checkpoint invalidation, queued input between
  tool rounds, running-job preservation, and reopen after compaction.
- Add a reference fixture that runs a long tool loop through compaction, saves,
  relaunches, and continues without losing the active task.

Exit criterion: repeat the reference `ds4-agent` long-context scenarios,
including compaction forced by a large tool result, stop during compaction, and
restart after a successful compaction. The same task state, recent turns, tool
contract, and running-job awareness must remain available.

## 2. 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.

## 3. 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.

### 3.1 SSD streaming — first runtime priority

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.

### 3.2 Speculative decoding: legacy MTP and DSpark

- 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.

### 3.3 Remaining Metal execution controls

- 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.

### 3.4 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.

## 4. Additional model execution

Start these only after the shared capacity and execution technology above is
stable. Catalog entries, settings, tokenizer work, or GGUF validation alone do
not make a model selectable for inference.

### 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.

## 5. 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.

## 6. 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.