# ADR-0012: Document model: a list of lines, `line.col` positions

- **Status:** Accepted
- **Date:** 2026-06-24
- **Deciders:** jka
- **Decision:** D12

## Context

The core owns the document (ADR-0003), so it needs a representation and a
coordinate system for positions and edits. Candidates range from a plain list of
lines to gap buffers and ropes.

## Decision

A buffer is an ordered list of line strings. Positions and ranges use `line.col`
with a 1-based line and a 0-based column, which is the index format of Tk's
`text` widget. An edit is a range replacement: replace `[start, end)` with text.
Insertion and deletion are special cases. Change events carry the replaced range
and the new text so other views can resynchronise.

## Alternatives considered

A gap buffer or rope would scale better to very large files. For source-file
sizes a list of lines is simple, readable and fast enough; the alternatives were
judged premature.

## Consequences

- The GUI maps core positions onto the Tk widget without conversion, keeping the
  view layer thin.
- The `line.col` index also suits a character-cell terminal.
- `line.col` strings must never pass through `expr`: `1.10` becomes the number
  `1.1`. This defect appeared three times (the edit proxy, the find bar and the
  `buffer.find` handler) and is now a documented rule and a regression test.
- Large-file handling (lazy loading) remains an open question.