about summary refs log tree commit diff
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-16 00:39:24 +0000
committerPjotr <wrk@bosa.lan>2026-11-16 00:39:24 +0000
commitc7bcd32190f0355ad3d6ba5a87ca7eec3fcf2604 (patch)
treee4eecc8c2f36bc7e7d53b686b39586b01aa40bc8
parent692456b495bb531d604670cf2122a8fec1603d24 (diff)
downloadai-memory-c7bcd32190f0355ad3d6ba5a87ca7eec3fcf2604.tar.gz
gists: freeze what was assessed, recompute only what was derived
A gist is a judgement about what an entry claims, so it must not drift once
made.  The store did not hold that invariant: db_backfill_gist ran

    update reasoning set gist = ?1 where id = ?2

for every row, so any migration that re-derived gists would have replaced
every assessed --gist with the body's first sentence.  It only escaped
notice because the backfill happens to run once, on the version 3 -> 4
upgrade.

reasoning.gist_source now says how each gist came about -- 'assessed' when
the caller said what the entry claims (--gist), 'derived' when it is the
body's first sentence -- and the backfill is guarded:

    where gist is null or gist_source = 'derived'

so a derived gist may be recomputed when the derivation improves, and an
assessed one is frozen for the life of the entry.  Version 5 of the schema
adds the column; a store that predates it cannot say which of its gists were
assessed, and the two mistakes are not equal -- labelling an assessed gist
derived lets a later migration overwrite a judgement, while labelling a
derived one assessed merely freezes a first sentence -- so existing gists
become 'assessed' and only rows with no gist are left to the backfill.

test/gist_immutable.sh pins it: record one assessed and one derived gist,
set user_version back to 3 so the next open re-runs the migration, and assert
both are byte-identical afterwards.  Against the old backfill the assessed
one changes and the test fails.

Measured on the production store (139 entries, version 4): the migration to 5
kept every gist and labelled all 139 assessed, no gist was blanked, and
listings (log, why, search) are unchanged.  Two new entries came out as
expected: ('Derived one', derived) and ('Assessed one', assessed).
-rw-r--r--db.odin37
-rw-r--r--main.odin13
-rw-r--r--schema.sql7
-rwxr-xr-xtest/gist_immutable.sh54
4 files changed, 106 insertions, 5 deletions
diff --git a/db.odin b/db.odin
index 89ebec7..7f7d44a 100644
--- a/db.odin
+++ b/db.odin
@@ -207,6 +207,20 @@ db_migrate :: proc(db: ^Db) -> bool {
 		version = 4
 	}
 
+	// Version 5: reasoning.gist_source, so a derived gist (the body's first
+	// sentence) can be recomputed while an assessed one is frozen.  A gist
+	// written before this column existed cannot be classified, and freezing is
+	// the safe answer: marking it 'assessed' means no later migration may touch
+	// it.  Rows with no gist at all are left alone for the backfill to fill.
+	if version == 4 {
+		if db_add_column(db, "reasoning", "gist_source", "text") {
+			if !db_label_existing_gists(db) {
+				return false
+			}
+		}
+		version = 5
+	}
+
 	if version > 0 {
 		if !db_exec(db, fmt.tprintf("pragma user_version = %d", version)) {
 			return false
@@ -311,6 +325,21 @@ sqlite_changes :: proc(db: ^Db) -> i64 {
 	return i64(sqlite3.changes(db.handle))
 }
 
+// db_label_existing_gists classifies gists written before gist_source existed.
+// Nothing in the store says whether such a gist was assessed or derived, and the
+// two errors are not equal: calling an assessed gist 'derived' lets a later
+// re-derivation overwrite a judgement, while calling a derived one 'assessed'
+// only freezes a first sentence.  So everything that is there becomes assessed,
+// and only rows with no gist at all are left for the backfill.
+db_label_existing_gists :: proc(db: ^Db) -> bool {
+	if !db_exec(db, "update reasoning set gist_source = 'assessed' " +
+	                "where gist is not null and gist_source is null") {
+		return false
+	}
+	return db_exec(db, "update reasoning set gist_source = 'derived' " +
+	                   "where gist is null and gist_source is null")
+}
+
 // db_backfill_gist gives entries written before version 4 a first-sentence
 // gist.  It is a floor, not a substitute: a recorded --gist says what the entry
 // claims, where the first sentence often only says what the entry is about.
@@ -339,8 +368,14 @@ db_backfill_gist :: proc(db: ^Db) -> bool {
 	}
 	// One statement per row: the binding has no sqlite3_reset (see the note in
 	// db_backfill_basename).
+	//
+	// `where gist is null or gist_source = 'derived'` is the whole point of
+	// gist_source: this used to rewrite every row, so an assessed --gist was one
+	// migration away from being replaced by the body's first sentence.
 	for row in rows {
-		u, uok := stmt(db, "update reasoning set gist = ?1 where id = ?2")
+		u, uok := stmt(db, "update reasoning set gist = ?1, " +
+		              "gist_source = coalesce(gist_source, 'derived') " +
+		              "where id = ?2 and (gist is null or gist_source = 'derived')")
 		if !uok {
 			db_exec(db, "rollback")
 			return false
diff --git a/main.odin b/main.odin
index b12fa22..f9d1d20 100644
--- a/main.odin
+++ b/main.odin
@@ -332,8 +332,8 @@ cmd_record :: proc(args: []string) -> bool {
 
 	s, sok := stmt(&db, `insert or ignore into reasoning
 	                       (commit_hash, session_id, step, created_at, kind,
-	                        basis, supersedes, gist, body)
-	                     values (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)`)
+	                        basis, supersedes, gist, gist_source, body)
+	                     values (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`)
 	if !sok {
 		return false
 	}
@@ -367,7 +367,14 @@ cmd_record :: proc(args: []string) -> bool {
 		stmt_bind_null(&s, 7)
 	}
 	stmt_bind_text(&s, 8, gist)
-	stmt_bind_text(&s, 9, body)
+	// assessed when the caller said what the entry claims, derived when it is the
+	// body's first sentence -- only the latter may ever be recomputed.
+	gist_source := "derived"
+	if gist_given {
+		gist_source = "assessed"
+	}
+	stmt_bind_text(&s, 9, gist_source)
+	stmt_bind_text(&s, 10, body)
 
 	if stmt_step(&s) != .Done {
 		return false
diff --git a/schema.sql b/schema.sql
index 0f19c35..e624369 100644
--- a/schema.sql
+++ b/schema.sql
@@ -45,6 +45,11 @@ create table if not exists reasoning (
 	-- One line: the claim itself, written when the context is in hand.  Listings
 	-- show this by default; the body is the long form.
 	gist        text,
+	-- Whether that one-line claim was ASSESSED (written with --gist, or set by
+	-- a reader who knew what the entry claims) or DERIVED (the body's first
+	-- sentence, a fallback).  Only derived gists may ever be rewritten: an
+	-- assessed gist is a judgement and is frozen for the life of the entry.
+	gist_source text,
 	body        text not null,
 	unique (session_id, step, kind)
 );
@@ -75,4 +80,4 @@ create trigger if not exists reasoning_after_update after update on reasoning be
 	insert into reasoning_fts (rowid, body) values (new.id, new.body);
 end;
 
-pragma user_version = 4;
+pragma user_version = 5;
diff --git a/test/gist_immutable.sh b/test/gist_immutable.sh
new file mode 100755
index 0000000..0b3b45b
--- /dev/null
+++ b/test/gist_immutable.sh
@@ -0,0 +1,54 @@
+#!/bin/sh
+# An assessed gist must survive a full re-migration; a derived one may be
+# recomputed.  This is the invariant gist_source exists for, and it used to be
+# broken: db_backfill_gist updated every row, so `--gist` was one migration away
+# from being replaced by the body's first sentence.
+#
+# Usage: test/gist_immutable.sh [path-to-ai-memory]
+set -eu
+BIN=${1:-${AI_MEMORY:-bin/ai-memory}}
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+DB=$WORK/store.sqlite
+
+$BIN --db "$DB" -C . init >/dev/null
+
+# One assessed gist, one derived (no --gist), and one assessed gist whose body's
+# first sentence is different -- so a re-derivation is detectable.
+$BIN --db "$DB" -C . record --session g --step 1 --kind conclusion \
+     --commit none --gist "ASSESSED claim about the first thing" \
+     --body "First sentence here. And a second one that says more." >/dev/null
+$BIN --db "$DB" -C . record --session g --step 2 --kind conclusion \
+     --commit none --body "Derived sentence. Another sentence follows." >/dev/null
+
+q() { python3 - "$DB" "$1" <<'PY'
+import sqlite3, sys
+db, sql = sys.argv[1], sys.argv[2]
+print(sqlite3.connect(db).execute(sql).fetchone())
+PY
+}
+
+before1=$(q "select gist, gist_source from reasoning where step = 1")
+before2=$(q "select gist, gist_source from reasoning where step = 2")
+
+# Force the re-migration path: a store that looks like version 3 (before gist
+# existed) makes the backfill run on the next open.
+q "select 1" >/dev/null
+python3 - "$DB" <<'PY'
+import sqlite3, sys
+c = sqlite3.connect(sys.argv[1]); c.execute('pragma user_version = 3'); c.commit()
+PY
+$BIN --db "$DB" -C . status >/dev/null
+
+after1=$(q "select gist, gist_source from reasoning where step = 1")
+after2=$(q "select gist, gist_source from reasoning where step = 2")
+
+if [ "$before1" != "$after1" ]; then
+	echo "FAIL: the assessed gist changed: $before1 -> $after1" >&2
+	exit 1
+fi
+if [ "$before2" != "$after2" ]; then
+	echo "FAIL: the derived gist changed: $before2 -> $after2" >&2
+	exit 1
+fi
+echo "ok: assessed gist frozen ($after1); derived gist kept ($after2)"