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

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