about summary refs log tree commit diff
path: root/schema.sql
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 /schema.sql
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).
Diffstat (limited to 'schema.sql')
-rw-r--r--schema.sql7
1 files changed, 6 insertions, 1 deletions
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;