From 947506c7b80db5be9bdb1b5a0c9ad0ba2884f349 Mon Sep 17 00:00:00 2001 From: claude Date: Tue, 4 Aug 2026 04:45:41 +0400 Subject: [PATCH] docs: a list is the fourth append-only shape (V-453) --- docs/design.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/design.md b/docs/design.md index a5db622..4d204ab 100644 --- a/docs/design.md +++ b/docs/design.md @@ -630,6 +630,31 @@ add a new principle; it applied the existing one at smaller and smaller scope. --- +## A list is the fourth shape + +Facts, notes and tasks were the three append-only shapes. `list_items` is the +fourth (Vikunja #453): an item, a status, and a list tag. + +It is not a task. Milk is not work, nothing prioritises it, and the ranker must +not start counting groceries as outstanding errands. It is not a fact either, +because it claims nothing about the world. What it is, is a set that grows and +shrinks. + +The property that makes the separate table worth it: no predicate reads a list. +Nothing ranks it, nothing nudges about it, the digestion worker ignores it. So +two people adding to the same list at once cost nothing — there is no order to +disagree about and no lifecycle past crossed-off. + +The unique index is the tasks one, per list, and live rows only. Saying "молоко" +twice before the shop is one line; saying it again next week, after the last one +was crossed off, is a new line. + +Spoken, it is four turns: add, read back, cross one item off, cross the lot off. +All four are matched deterministically in `internal/router/list.go` and all four +run at stage 0, because an add and a read-back are cheap and should not depend on +the resident model having a good turn. Crossing one item off claims the turn only +when the list holds that item, which is what keeps "купил новый ноутбук" a note. + ## Calendar Integration with **Radicale** (self-hosted CalDAV), not Nextcloud. Scope is