# SLeeLa Debugger — 1-2-3-4 Completion Framework Version: 0.7.0 Date: 2026-09-27 This document defines the four-stage development contract for the SLeeLa Debugger: **1. Model → 2. Implement → 3. Integrate → 4. Verify**. ## 1 — MODEL Define every capability as a stable SLeeLa concept with typed structures, lifecycle, platform-neutral semantics, capability state, errors, security boundaries, evidence requirements, and versioned documentation. Covered model areas include breakpoints, watchpoints, threads, stacks, symbols, registers, memory, exceptions, signals, stop reasons, expressions, evidence, checkpoints/replay, crash dumps, sanitizers, memory diagnostics, profiling, coverage, synchronization evidence, persistent artifacts, and security authorization. ## 2 — IMPLEMENT Make the modeled behavior real in source. Require deterministic state transitions, bounded inputs, explicit failure handling, truthful native-support claims, C/C++ integration where required, and executable tests. The portable DebugEngine and DiagnosticsEngine provide the domain layer. Native operating-system mechanisms remain separate implementations. ## 3 — INTEGRATE Connect capabilities through: **Target → Native Backend → DebugEngine → DebugSession/Event Bus → ActionController → Diagnostics/Evidence → Test Suite/UI/HTTP/DAP** Integration must confirm backend success, preserve native evidence, associate stops with evidence, retain build identity, enforce security policy, report truthful capabilities, and never silently substitute a model-only simulation for native behavior. Integration targets include Linux ptrace, macOS LLDB, Windows Debug API, DWARF/PDB/ELF/Mach-O/PE source and symbol mapping, hardware watchpoints, real thread/stack inspection, crash dumps, sanitizer adapters, DAP, terminal UI, HTTP debugging, plugins, and Test Suite connections. ## 4 — VERIFY A capability reaches verified state only after executable evidence exists. Required evidence: successful build; positive test; negative/failure test; truthful capability state; reproducible diagnostics; enforced security policy; matching documentation; identified platform behavior; and regression coverage. ## Status Vocabulary | State | Meaning | |---|---| | Modelled | Contract and data model exist. | | Implemented | Behavior exists in source. | | Integrated | Connected to its execution/backend path. | | Tested | An executable test demonstrates the behavior. | | Production-ready | Project-defined release gates are satisfied. | ## Debugger Package Map ### 1. Execution Breakpoints, watchpoints, threads, stacks, registers, memory, expressions, execution control, checkpoints, and replay. ### 2. Diagnostics Crash evidence, sanitizer findings, memory diagnostics, profiling, coverage, synchronization evidence, and stop explanations. ### 3. Integration Native backends, source mapping, symbol services, HTTP debugging, DAP, terminal UI, plugins, and Test Suite connections. ### 4. Verification Capability reports, deterministic tests, evidence bundles, session artifacts, regression fixtures, and release gates. ## Artifact Contract Persistent sessions use the `.sleela-debug/` model to preserve session identity, events/timeline, breakpoints/watchpoints, threads/stacks, registers/memory maps, modules/symbols, evidence, coverage, crash information, replay/checkpoint metadata, and build/source identity. ## Version Progression ### 0.7.0 — Four-Stage Debugger Contract Adds the 1-2-3-4 Model → Implement → Integrate → Verify framework and incorporates the DebugEngine/DiagnosticsEngine expansion. ### 0.6.0 — Native and Reproduction Roadmap Established the native-backend, reproduction, evidence, sanitizer, DAP, session, plugin, and security roadmap. ### 0.5.0 — Second Arrangement Established the unified event bus, timeline, stop explanation, crash evidence, deterministic sessions, build identity, test integration, profiles, DAP architecture, and evidence chain. ### 1.0.0 Target Requires the four stages to be satisfied for the project-defined production contract, with native platform capability clearly separated from portable modeled behavior. ## Completion Rule **No feature is complete merely because its header exists.** A debugger feature is complete for release purposes when it passes: **1 — Model → 2 — Implement → 3 — Integrate → 4 — Verify** The verification record must identify what was tested, on which platform, against which executable/source revision, and with which debugger capability state.