# ADR 0001: Core analysis contracts - Status: accepted - Date: 2026-09-29 ## Context John Slop needs stable semantics before its proof-of-concept modules are split into a library, CLI, formatter, and language server. In particular, consumers need to know what a confidence score means, how source locations are represented, whether formatting is destructive by default, and whether archive members can be rewritten. ## Decision ### Confidence represents evidence, not authorship The detector reports confidence that configured, observable low-care signals are present. It does not report the probability that content is AI-generated and must not present a score as an authorship determination. Every score must be decomposable into source-labelled findings from stable rule IDs. ### UTF-8 byte spans are canonical Internal source spans are zero-based, half-open UTF-8 byte ranges into the exact source snapshot analyzed. This matches Rust string and regex offsets and avoids lossy conversions inside the detection engine. Presentation adapters validate boundaries and convert to their required representation: `miette::SourceSpan` for terminal diagnostics and UTF-16 line/character positions for LSP. ### Formatter writes are opt-in The formatter's default file behavior is read-only. It may print transformed text or a diff, while an explicit `--write` is required to mutate files. `--check` only reports whether an edit would be made. A failed analysis, configuration load, or edit validation must leave the original file untouched. ### Archive mutation is deferred The first formatter release may inspect text members in supported ZIP-based containers, but it will not rewrite archives, DOCX, XLSX, or PPTX files. In-place archive editing has additional integrity, metadata-preservation, atomicity, and decompression-safety concerns. It requires a separate decision record and test plan before implementation. ## Consequences - User-facing terminology must describe evidence and request review rather than accuse an author. - The domain model stores byte ranges, while the LSP owns a tested UTF-16 mapping layer tied to document versions. - Replacement planning remains a pure operation; filesystem mutation lives in an explicit formatter adapter. - Archive inputs can produce findings but an attempted archive write produces a clear unsupported-operation diagnostic.