Home /Modules/debugger/1-2-3-4.md

1-2-3-4.md

debugger/1-2-3-4.md · 70 line(s) · markdown

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

StateMeaning
ModelledContract and data model exist.
ImplementedBehavior exists in source.
IntegratedConnected to its execution/backend path.
TestedAn executable test demonstrates the behavior.
Production-readyProject-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.