@jossuealcala/madre 0.5.2 → 0.7.0

package/src/memory.mjs

@@ -38,6 +38,67 @@ export const MEMORY_KINDS = ['decision', 'fact', 'preference', 'question', ABERR
 // What the room will hand an agent: knowledge that still stands. Everything else is archive.
 export const STANDING_KINDS = MEMORY_KINDS.filter((kind) => kind !== ABERRATION);
 
+// Where a memory stands aboard, which is a different question from what it is. The five kinds say
+// WHAT a note is; the four zones say what standing it has, and standing is what the recall obeys.
+// The two are orthogonal: a decision can be in any zone. Ids travel in the database and never
+// move; the ship's words for them are said on screen only.
+//
+//   HOLD        just distilled, nobody has confirmed it                   · recalled
+//   BRIDGE      the human said it worked                                  · recalled
+//   MEDBAY      quarantined: it is false, or it failed                    · never recalled
+//   JETTISONED  put out of circulation, kept so it is not relearned       · never recalled
+//
+// Not `airlock`: in this room that word already means permission mode #4, and one word means one
+// thing. The Spanish word on screen is still ESCLUSA.
+export const HOLD = 'hold';
+export const BRIDGE = 'bridge';
+export const MEDBAY = 'medbay';
+export const JETTISONED = 'jettisoned';
+export const MEMORY_ZONES = [HOLD, BRIDGE, MEDBAY, JETTISONED];
+// The zones a note can travel into a turn from. Everything else is archive the room keeps and
+// never hands over.
+export const RECALLED_ZONES = [HOLD, BRIDGE];
+
+// What the human can say about a reply. Four verdicts and the clearing — one act, one field: the
+// human judges a reply once, and two fields for one act would be a lie about what they did.
+//
+//   good        it worked                    · the note it left stands confirmed
+//   preference  this is how I want it done   · the same, and it is worth training toward
+//   bad         it failed                    · the note is quarantined and stops travelling
+//   never       do not do this again         · the note is put out, and the pair trains against it
+//   none        no judgement                 · back to where the rule alone would put it
+//
+// Ordered worst first, and read in that order: a note is distilled from several replies and takes
+// the WORST verdict among them. If one exchange it came from was wrong the note is suspect however
+// good the rest were, and quarantine is the cheap mistake.
+export const VERDICTS = ['never', 'bad', 'preference', 'good', 'none'];
+export const NEGATIVE_VERDICTS = ['never', 'bad'];
+export const POSITIVE_VERDICTS = ['preference', 'good'];
+
+// The gate, as one line of SQL instead of five copies of two rules. Everything the room may hand
+// a turn stands in one of these zones; everything else is archive it keeps and never serves.
+const ZONE_GATE = `zone IN (${RECALLED_ZONES.map((zone) => `'${zone}'`).join(', ')})`;
+// Same question asked of a row already in hand.
+export const travels = (row) => RECALLED_ZONES.includes(row?.zone ?? zoneFor(row));
+
+// Where today's rules put a note, with no reaction involved: this is the whole of what the two
+// scattered gates in the recall mean, written once. Keeping it as a function is what lets the
+// next step prove the column says exactly what those gates said, and not something close to it.
+export function zoneFor(row, verdict = null) {
+  if (!row) return null;
+  // The archive's own judgement outranks the human's thumb, and on purpose: «this is false» and
+  // «that reply helped me» are different claims, and a thumb up must never bring back a note the
+  // room already established was wrong.
+  if (row.kind === ABERRATION) return MEDBAY;
+  if ((row.refutedBy ?? row.refuted_by ?? null) !== null) return JETTISONED;
+  // A note distilled from several replies takes the worst verdict among them: if one of the
+  // exchanges it came from was wrong, the note is suspect, and quarantine is the cheap mistake.
+  if (verdict === 'never') return JETTISONED;
+  if (verdict === 'bad') return MEDBAY;
+  if (verdict === 'preference' || verdict === 'good') return BRIDGE;
+  return HOLD;
+}
+
 // The dedup key. An aberration almost always quotes the claim it refutes word for word, so on a
 // shared key the archive would silently drop the refutation as a duplicate of the thing it is
 // refuting. Aberrations are keyed in their own space: one of each still dedupes, and a false
@@ -203,6 +264,9 @@ export class RoomMemory {
       );
       CREATE INDEX IF NOT EXISTS recalls_memory ON recalls(memory_id, id DESC);
       CREATE INDEX IF NOT EXISTS recalls_batch ON recalls(batch);
+      -- The human's verdicts, folded out of the ledger. Nothing is accumulated here: the ledger is
+      -- the truth and this is a cache of its last word per reply, rebuilt on every catch-up.
+      CREATE TABLE IF NOT EXISTS verdicts (message_id TEXT PRIMARY KEY, verdict TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS entry_vectors (sequence INTEGER PRIMARY KEY, model TEXT NOT NULL, vec BLOB NOT NULL);
       CREATE TABLE IF NOT EXISTS memory_vectors (id INTEGER PRIMARY KEY, model TEXT NOT NULL, vec BLOB NOT NULL);
     `);
@@ -234,6 +298,15 @@ export class RoomMemory {
     for (const column of ['contradicts INTEGER', 'correction TEXT', 'detector TEXT', 'confidence REAL', 'refuted_by INTEGER']) {
       if (!columns.includes(column.split(' ')[0])) this.#db.exec(`ALTER TABLE memories ADD COLUMN ${column}`);
     }
+    // Standing, as a column. Older files are seeded from the two rules the recall already applied,
+    // so nothing changes meaning on the way in — and the seeding runs only the once, inside the
+    // branch that creates the column: after this a reaction is what moves a note, and a backfill
+    // on every boot would quietly undo them.
+    if (!columns.includes('zone')) {
+      this.#db.exec(`ALTER TABLE memories ADD COLUMN zone TEXT NOT NULL DEFAULT '${HOLD}'`);
+      this.#db.exec(`UPDATE memories SET zone = '${MEDBAY}' WHERE kind = '${ABERRATION}'`);
+      this.#db.exec(`UPDATE memories SET zone = '${JETTISONED}' WHERE refuted_by IS NOT NULL`);
+    }
   }
 
   /* ---------- embeddings ---------- */
@@ -401,6 +474,28 @@ export class RoomMemory {
   }
   memoryCount() { return this.#db.prepare('SELECT COUNT(*) AS n FROM memories').get().n; }
 
+  // What the archive did, day by day, and what it is made of, as counts and nothing else: no
+  // text leaves through here, so the MEMORY dashboard can read it without the designation.
+  // Days are this machine's calendar days, which is what a person reading a chart means by one.
+  activity({ days = 30 } = {}) {
+    if (!this.#db) return null;
+    const since = `-${Math.max(1, Math.floor(days)) - 1} days`;
+    const perDay = (sql) => this.#db.prepare(sql).all(since).map((row) => [row.day, row.n]);
+    const grouped = (column) => Object.fromEntries(this.#db.prepare(`SELECT ${column} AS k, COUNT(*) AS n FROM memories GROUP BY ${column}`).all().map((row) => [row.k ?? HOLD, row.n]));
+    return {
+      entries: perDay("SELECT date(timestamp, 'localtime') AS day, COUNT(*) AS n FROM entries WHERE timestamp IS NOT NULL AND date(timestamp, 'localtime') >= date('now', 'localtime', ?) GROUP BY day"),
+      memories: perDay("SELECT date(created, 'localtime') AS day, COUNT(*) AS n FROM memories WHERE date(created, 'localtime') >= date('now', 'localtime', ?) GROUP BY day"),
+      // A turn that reached into the archive, once per turn however many notes it carried.
+      recalls: perDay("SELECT day, COUNT(*) AS n FROM (SELECT date(MIN(at), 'localtime') AS day FROM recalls GROUP BY batch) WHERE day >= date('now', 'localtime', ?) GROUP BY day"),
+      kinds: grouped('kind'),
+      agents: grouped('agent'),
+      zones: grouped('zone'),
+      via: Object.fromEntries(this.#db.prepare('SELECT via AS k, COUNT(*) AS n FROM recalls GROUP BY via').all().map((row) => [row.k, row.n])),
+      turns: this.#db.prepare('SELECT COUNT(DISTINCT batch) AS n FROM recalls').get().n,
+      reached: this.#db.prepare('SELECT COUNT(*) AS n FROM memories WHERE recalled > 0').get().n,
+    };
+  }
+
   // The next batch to distil: the NEWEST entries nobody has distilled, cut at a
   // character budget so one run stays cheap, returned in ledger order. What was
   // just said becomes memory first; an old backlog drains behind it, batch by
@@ -422,7 +517,7 @@ export class RoomMemory {
   // Stores distilled memories; a note already held (same text, ignoring case
   // and punctuation) is not stored twice. Returns how many were new.
   addMemories(list, { agent, fromSequence, throughSequence, origin = 'distilled', messageId = null }) {
-    const insert = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id, correction, detector, confidence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const insert = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id, correction, detector, confidence, zone) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
     const now = new Date().toISOString();
     let added = 0;
     this.#db.exec('BEGIN');
@@ -439,14 +534,14 @@ export class RoomMemory {
         // note that refutes it is wired up later, by whoever can name the id.
         const aberrant = kind === ABERRATION;
         const correction = aberrant ? this.#guard(String(memory.correction ?? '').trim()) || null : null;
-        const result = insert.run(now, kind, text, memoryKey(kind, text), fromSequence ?? sources[0] ?? 0, throughSequence ?? sources.at(-1) ?? 0, JSON.stringify(sources), agent, origin, messageId, correction, aberrant ? (memory.detector ?? agent) : null, aberrant ? (Number.isFinite(memory.confidence) ? memory.confidence : null) : null);
+        const result = insert.run(now, kind, text, memoryKey(kind, text), fromSequence ?? sources[0] ?? 0, throughSequence ?? sources.at(-1) ?? 0, JSON.stringify(sources), agent, origin, messageId, correction, aberrant ? (memory.detector ?? agent) : null, aberrant ? (Number.isFinite(memory.confidence) ? memory.confidence : null) : null, aberrant ? MEDBAY : HOLD);
         added += Number(result.changes ?? 0);
         if (aberrant && Number(result.changes ?? 0)) {
           const id = Number(result.lastInsertRowid);
           const target = this.#refutedBy(text);
           if (target) {
             this.#db.prepare('UPDATE memories SET contradicts = ? WHERE id = ?').run(target, id);
-            this.#db.prepare('UPDATE memories SET refuted_by = ? WHERE id = ? AND refuted_by IS NULL').run(id, target);
+            this.#db.prepare(`UPDATE memories SET refuted_by = ?, zone = '${JETTISONED}' WHERE id = ? AND refuted_by IS NULL`).run(id, target);
           }
         }
       }
@@ -471,7 +566,7 @@ export class RoomMemory {
     const terms = new Set(normalizeMemory(text).split(' ').filter((word) => word.length > 2));
     if (terms.size < 3) return null;
     let best = null;
-    const standing = this.#db.prepare(`SELECT id, text FROM memories WHERE kind != '${ABERRATION}' AND refuted_by IS NULL ORDER BY id DESC LIMIT 200`).all();
+    const standing = this.#db.prepare(`SELECT id, text FROM memories WHERE ${ZONE_GATE} ORDER BY id DESC LIMIT 200`).all();
     for (const row of standing) {
       const other = new Set(normalizeMemory(row.text).split(' ').filter((word) => word.length > 2));
       if (other.size < 3) continue;
@@ -494,11 +589,11 @@ export class RoomMemory {
     const refuted = Number.isInteger(contradicts) ? this.#db.prepare(`SELECT id, kind FROM memories WHERE id = ? AND kind != '${ABERRATION}'`).get(contradicts) : null;
     this.#db.exec('BEGIN');
     try {
-      const result = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, contradicts, correction, detector, confidence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
-        .run(new Date().toISOString(), ABERRATION, claim, memoryKey(ABERRATION, claim), fromSequence ?? cites[0] ?? 0, throughSequence ?? cites.at(-1) ?? 0, JSON.stringify(cites), agent, 'flagged', refuted?.id ?? null, this.#guard(String(correction ?? '').trim()) || null, detector, Number.isFinite(confidence) ? confidence : null);
+      const result = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, contradicts, correction, detector, confidence, zone) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+        .run(new Date().toISOString(), ABERRATION, claim, memoryKey(ABERRATION, claim), fromSequence ?? cites[0] ?? 0, throughSequence ?? cites.at(-1) ?? 0, JSON.stringify(cites), agent, 'flagged', refuted?.id ?? null, this.#guard(String(correction ?? '').trim()) || null, detector, Number.isFinite(confidence) ? confidence : null, MEDBAY);
       if (!Number(result.changes ?? 0)) { this.#db.exec('ROLLBACK'); return null; }   // already known
       const id = Number(result.lastInsertRowid);
-      if (refuted) this.#db.prepare('UPDATE memories SET refuted_by = ? WHERE id = ? AND refuted_by IS NULL').run(id, refuted.id);
+      if (refuted) this.#db.prepare(`UPDATE memories SET refuted_by = ?, zone = '${JETTISONED}' WHERE id = ? AND refuted_by IS NULL`).run(id, refuted.id);
       this.#db.exec('COMMIT');
       return { id, refuted: refuted?.id ?? null };
     } catch (error) {
@@ -515,7 +610,7 @@ export class RoomMemory {
     if (!row) return null;
     this.#db.exec('BEGIN');
     try {
-      this.#db.prepare('UPDATE memories SET refuted_by = NULL WHERE refuted_by = ?').run(row.id);
+      this.#db.prepare(`UPDATE memories SET refuted_by = NULL, zone = '${HOLD}' WHERE refuted_by = ?`).run(row.id);
       this.#db.prepare('DELETE FROM memories WHERE id = ?').run(row.id);
       this.#db.prepare('DELETE FROM memory_vectors WHERE id = ?').run(row.id);
       this.#db.exec('COMMIT');
@@ -550,6 +645,13 @@ export class RoomMemory {
   }
 
   // The latest entries, newest first, one line each.
+  // Where a reply landed in the ledger. The join a verdict travels along — reply id to sequence to
+  // the notes that cite it — starts here, and having it named makes it addressable from outside.
+  sequenceOf(messageId) {
+    if (!this.#db) return null;
+    return this.#db.prepare('SELECT sequence FROM entries WHERE message_id = ? ORDER BY sequence DESC LIMIT 1').get(String(messageId ?? ''))?.sequence ?? null;
+  }
+
   timeline({ since = 0, limit = 30 } = {}) {
     return this.#db.prepare('SELECT sequence, timestamp, role, sender, target, substr(text, 1, 200) AS text FROM entries WHERE sequence > ? ORDER BY sequence DESC LIMIT ?').all(since, limit);
   }
@@ -564,7 +666,7 @@ export class RoomMemory {
       this.#db.prepare('DELETE FROM recalls WHERE memory_id = ?').run(id);
       // A note quarantined by this one comes back: with the aberration gone there is nothing
       // holding it out of circulation, and a memory must never be lost to a pointer at nothing.
-      this.#db.prepare('UPDATE memories SET refuted_by = NULL WHERE refuted_by = ?').run(id);
+      this.#db.prepare(`UPDATE memories SET refuted_by = NULL, zone = '${HOLD}' WHERE refuted_by = ?`).run(id);
       this.#db.prepare('DELETE FROM memories WHERE id = ?').run(id);
       this.#db.exec('COMMIT');
     } catch (error) { this.#db.exec('ROLLBACK'); throw error; }
@@ -605,12 +707,31 @@ export class RoomMemory {
     return rows.map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
   }
 
+  // What the archivist is told before it reads a batch, now that a note has standing. Two lists
+  // and not one, because they say opposite things: what the room already holds (so it is not
+  // written twice) and what the room THREW OUT (so it is not learned again). Until this, the
+  // archivist got the newest dozen notes whatever their standing — including things the room had
+  // established were false — under a heading that only said «do not repeat».
+  //
+  // The standing list leads with the BRIDGE: what the human confirmed is the part worth not
+  // contradicting. The discarded list is everything out of circulation, newest first, and it is
+  // left out entirely when there is nothing to say — a heading with no rows under it would be
+  // prompt the room pays for and the model learns nothing from.
+  briefing({ standing = 12, discarded = 6 } = {}) {
+    if (!this.#db) return { standing: [], discarded: [] };
+    const pick = (where, order, limit) => this.#db.prepare(`SELECT id, kind, text, zone FROM memories WHERE ${where} ORDER BY ${order} LIMIT ?`).all(limit);
+    return {
+      standing: pick(ZONE_GATE, `zone = '${BRIDGE}' DESC, id DESC`, standing),
+      discarded: pick(`NOT (${ZONE_GATE})`, 'id DESC', discarded),
+    };
+  }
+
   memories({ limit = 50, kind = null } = {}) {
     if (kind) {
-      return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories WHERE kind = ? ORDER BY id DESC LIMIT ?').all(kind, limit)
+      return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy, zone FROM memories WHERE kind = ? ORDER BY id DESC LIMIT ?').all(kind, limit)
         .map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
     }
-    return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories ORDER BY id DESC LIMIT ?').all(limit)
+    return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy, zone FROM memories ORDER BY id DESC LIMIT ?').all(limit)
       .map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
   }
 
@@ -628,7 +749,7 @@ export class RoomMemory {
     const scores = new Map();
     // Nothing that is false and nothing that has been refuted travels into a turn. This is the
     // gate: an archive that hands its own hallucinations back to the room repeats them.
-    const lookup = this.#db.prepare(`SELECT m.id FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid WHERE memories_fts MATCH ? AND m.through_sequence < ? AND m.kind != '${ABERRATION}' AND m.refuted_by IS NULL LIMIT 500`);
+    const lookup = this.#db.prepare(`SELECT m.id FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid WHERE memories_fts MATCH ? AND m.through_sequence < ? AND m.${ZONE_GATE} LIMIT 500`);
     for (const term of terms) {
       let rows;
       try { rows = lookup.all(`"${term.replaceAll('"', '""')}"`, beforeSequence); } catch { continue; }
@@ -638,10 +759,10 @@ export class RoomMemory {
     }
     const ids = RoomMemory.fuse(scores, semantic).map(([id]) => id);
     if (fallback && ids.length < 2) {
-      const recent = this.#db.prepare("SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') AND refuted_by IS NULL ORDER BY id DESC LIMIT ?").all(beforeSequence, limit);
+      const recent = this.#db.prepare(`SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') AND ${ZONE_GATE} ORDER BY id DESC LIMIT ?`).all(beforeSequence, limit);
       for (const { id } of recent) if (!ids.includes(id)) ids.push(id);
     }
-    const fetch = this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories WHERE id = ?');
+    const fetch = this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, contradicts, correction, detector, confidence, refuted_by AS refutedBy, zone FROM memories WHERE id = ?');
     const chosen = [];
     let remaining = Math.max(0, maxChars);
     let cursor = 0;
@@ -660,7 +781,7 @@ export class RoomMemory {
         cursor += 1;
         // The semantic side of the search does not go through the gate above, so it is checked
         // here as well: one path in means one path to keep clean, and there are two.
-        if (!row || row.kind === ABERRATION || row.refutedBy !== null) continue;
+        if (!row || !travels(row)) continue;
         take(row, 'search');
       }
     };
@@ -674,7 +795,7 @@ export class RoomMemory {
       for (const mate of this.associates(seeds, { limit: reserve })) {
         if (chosen.length >= limit) break;
         const row = fetch.get(mate.id);
-        if (!row || row.kind === ABERRATION || row.refutedBy !== null) continue;
+        if (!row || !travels(row)) continue;
         if (row.throughSequence >= beforeSequence) continue;   // it is already in the window
         take(row, 'cascade');
       }
@@ -824,11 +945,94 @@ export class RoomMemory {
     return added;
   }
 
-  // Indexes whatever the ledger holds beyond the last sequence seen.
+  /* ---------- verdicts: the human's reaction, and where it leaves a note standing ---------- */
+
+  // The worst verdict among the replies a note was distilled from. Worst, not newest: a note that
+  // came partly from an exchange the human marked wrong is suspect however good the other half was.
+  #verdictFor(id) {
+    const rows = this.#db.prepare(`
+      SELECT v.verdict FROM memories m, json_each(m.sources) src
+      JOIN entries e ON e.sequence = src.value
+      JOIN verdicts v ON v.message_id = e.message_id
+      WHERE m.id = ?`).all(Number(id)).map((row) => row.verdict);
+    return VERDICTS.find((verdict) => verdict !== 'none' && rows.includes(verdict)) ?? null;
+  }
+
+  // Recomputes standing for a handful of notes. The zone is a function of the rule plus the fold,
+  // so recomputing is always safe and never drifts — which is the whole reason a reaction can
+  // arrive days after the batch was distilled.
+  #restand(ids) {
+    const read = this.#db.prepare('SELECT id, kind, refuted_by AS refutedBy, zone FROM memories WHERE id = ?');
+    const write = this.#db.prepare('UPDATE memories SET zone = ? WHERE id = ?');
+    let moved = 0;
+    for (const id of ids) {
+      const row = read.get(Number(id));
+      if (!row) continue;
+      const zone = zoneFor(row, this.#verdictFor(row.id));
+      if (zone === row.zone) continue;
+      write.run(zone, row.id);
+      moved += 1;
+    }
+    return moved;
+  }
+
+  // The same rule over the whole archive, as one statement. A query per note was enough to make a
+  // room with a long ledger slower to open, and startup latency is not a place to spend.
+  // The CASE is `zoneFor` in SQL and the test holds the two to each other.
+  #restandAll() {
+    const cited = (verdict) => `EXISTS (SELECT 1 FROM json_each(memories.sources) src JOIN entries e ON e.sequence = src.value JOIN verdicts v ON v.message_id = e.message_id WHERE v.verdict = '${verdict}')`;
+    return Number(this.#db.prepare(`
+      UPDATE memories SET zone = CASE
+        WHEN kind = '${ABERRATION}' THEN '${MEDBAY}'
+        WHEN refuted_by IS NOT NULL THEN '${JETTISONED}'
+        WHEN ${cited('never')} THEN '${JETTISONED}'
+        WHEN ${cited('bad')} THEN '${MEDBAY}'
+        WHEN ${cited('preference')} OR ${cited('good')} THEN '${BRIDGE}'
+        ELSE '${HOLD}' END`).run().changes ?? 0);
+  }
+
+  // A reply judged. Only the notes that CITE that reply move: a batch spans hundreds of sequences
+  // in a real room, so standing on the batch range would make one thumb speak for exchanges the
+  // human never looked at. A note whose sources are empty is out of a thumb's reach, and that is
+  // the honest limit of this.
+  judge(messageId, verdict) {
+    if (!this.#db) return 0;
+    const id = String(messageId ?? '').trim();
+    if (!id) return 0;
+    if (VERDICTS.includes(verdict) && verdict !== 'none') this.#db.prepare('INSERT INTO verdicts (message_id, verdict) VALUES (?, ?) ON CONFLICT(message_id) DO UPDATE SET verdict = excluded.verdict').run(id, verdict);
+    else this.#db.prepare('DELETE FROM verdicts WHERE message_id = ?').run(id);
+    const touched = this.#db.prepare(`
+      SELECT DISTINCT m.id FROM memories m, json_each(m.sources) src
+      JOIN entries e ON e.sequence = src.value
+      WHERE e.message_id = ?`).all(id).map((row) => row.id);
+    return this.#restand(touched);
+  }
+
+  // Indexes whatever the ledger holds beyond the last sequence seen, and folds every verdict that
+  // ledger carries. Over the whole ledger on purpose: it is cheap, it is idempotent, and it is
+  // what lets a thumb pressed before any of this existed take effect on the next start.
+  //
+  // Applied event by event and never as a wipe-and-refill. There is one archive per room but one
+  // LEDGER PER CONVERSATION, and this is handed whichever one is open: emptying the table first
+  // would quietly drop every verdict given in the other conversations, and their notes would fall
+  // back to the hold on the next restart. A clearing is still a clearing — `none` deletes its row —
+  // so applying in order leaves the same result whichever conversation is replayed.
   async catchUp(store) {
     const last = this.lastSequence();
     const events = await store.readAll();
-    return this.index(events.filter((event) => event.sequence > last));
+    const added = this.index(events.filter((event) => event.sequence > last));
+    const write = this.#db.prepare('INSERT INTO verdicts (message_id, verdict) VALUES (?, ?) ON CONFLICT(message_id) DO UPDATE SET verdict = excluded.verdict');
+    const clear = this.#db.prepare('DELETE FROM verdicts WHERE message_id = ?');
+    for (const event of events) {
+      if (event?.type !== 'message.rated') continue;
+      const messageId = String(event.payload?.messageId ?? '');
+      if (!messageId) continue;
+      const verdict = event.payload?.rating;
+      if (VERDICTS.includes(verdict) && verdict !== 'none') write.run(messageId, verdict);
+      else clear.run(messageId);
+    }
+    this.#restandAll();
+    return added;
   }
 
   // Older exchanges matched to a request. Each term is looked up on its own

package/src/modules/ahp.mjs

@@ -11,7 +11,7 @@ import { readJson, gitToplevel, findOnPath, packageVersion } from './helpers.mjs
 // adapter yet, so it is simply not requested.
 const AHP_PLATFORMS = { codex: 'codex', claude: 'claude', opencode: 'opencode' };
 const PACKAGE = '@jossuealcala/ahp-plus';
-const VERSION = '1.4.1';
+const VERSION = '1.4.2';
 
 async function detect(projectRoot) {
   const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));

package/src/modules/ash-policy.mjs

@@ -0,0 +1,67 @@
+// Ash changes only the requested shape of an answer. This policy is pure and local: it neither
+// rewrites the human's request nor changes model, context, tools or permissions.
+
+const EXPLICIT_LENGTH = /\b(?:en|in|m[aá]ximo|max(?:imum)?|exact(?:ly|amente)?|at most|no more than)\s+(?:\w+\s+){0,3}\d+\s*(?:palabras?|words?|l[ií]neas?|lines?|p[aá]rrafos?|paragraphs?)\b/i;
+const CODE_TASK = /```|`[^`\n]+`|\b(?:c[oó]digo|code|implementa|implement|parche|patch|funci[oó]n|function|clase|class|script|comando|command|regex|sql|json|html|css|swift|javascript|typescript)\b/i;
+const STRUCTURED_TASK = /\b(?:tabla|table|lista|list|pasos?|steps?|compar(?:a|e|aci[oó]n)|audit(?:a|ar|oria)?|review|revisa|diagn[oó]stic|plan)\b/i;
+
+export function ashInstruction(text = '') {
+  const request = String(text ?? '');
+  const base = 'Ash: answer in compact prose. Say it once, drop the preamble and the summary of what you are about to say, and keep names, negation, numbers, paths, safety details and any ```pulse block exactly as they are. Brevity is in how you write, never in what you leave out.';
+  const safeguards = [];
+  if (EXPLICIT_LENGTH.test(request)) safeguards.push('The human set a length or format: follow it exactly; Ash does not shorten it further.');
+  if (CODE_TASK.test(request)) safeguards.push('Keep code and commands complete; shorten only the prose around them.');
+  if (STRUCTURED_TASK.test(request)) safeguards.push('Keep the requested structure and every finding; compress repeated explanation, not evidence.');
+  if (!safeguards.length) safeguards.push('For a simple request, lead with the answer and stop when the necessary qualification is complete.');
+  return `${base} ${safeguards.join(' ')}`;
+}
+
+const unique = (values) => [...new Set(values.filter(Boolean))];
+
+function exactAnchors(text) {
+  const source = String(text ?? '');
+  return unique([
+    ...[...source.matchAll(/`([^`\n]+)`/g)].map((match) => match[1]),
+    ...source.match(/(?:[A-Za-z]:\\[^\s"'`]+|(?:\.{0,2}\/|\/)?(?:[\w.-]+\/)+[\w.-]+)/g) ?? [],
+    ...source.match(/@[a-z0-9_-]+\b/gi) ?? [],
+    ...source.match(/\b[A-Z][A-Z0-9_+.-]{2,}\b/g) ?? [],
+    ...source.match(/\b\d+(?:[.,]\d+)?%?\b/g) ?? [],
+  ]);
+}
+
+function requestedLimit(text) {
+  const match = String(text ?? '').match(/\b(?:m[aá]ximo|max(?:imum)?|at most|no more than)\s+(\d+)\s*(palabras?|words?|l[ií]neas?|lines?)\b/i);
+  if (!match) return null;
+  return { amount: Number(match[1]), unit: /line|l[ií]nea/i.test(match[2]) ? 'lines' : 'words' };
+}
+
+// Phase 4 is deliberately a checker, not a second agent turn. A retry could repeat writes or
+// external actions; review evidence is visible instead. Exact anchors are required only when the
+// human explicitly asked to preserve them, so ordinary answers are not forced to echo a request.
+export function validateAshReply({ request = '', response = '' } = {}) {
+  const input = String(request ?? '');
+  const output = String(response ?? '');
+  const issues = [];
+  const checked = ['non-empty', 'code-fences', 'pulse-position'];
+  if (!output.trim()) issues.push('empty response');
+  if ((output.match(/```/g) ?? []).length % 2 !== 0) issues.push('unclosed code fence');
+  const pulse = [...output.matchAll(/```pulse\s*\n[\s\S]*?```/gi)].at(-1);
+  if (pulse && output.slice(pulse.index + pulse[0].length).trim()) issues.push('text after ```pulse block');
+
+  const limit = requestedLimit(input);
+  if (limit) {
+    checked.push(`max-${limit.unit}`);
+    const count = limit.unit === 'lines' ? output.trim().split(/\r?\n/).length : (output.trim().match(/\S+/g) ?? []).length;
+    if (count > limit.amount) issues.push(`${count} ${limit.unit}, maximum ${limit.amount}`);
+  }
+
+  const exact = /\b(?:keep|preserve|include|repeat|mant[eé]n|conserva|incluye|repite)\b[^\n.]{0,100}\b(?:exact(?:ly|amente)?|literal(?:ly|mente)?|tal cual|sin cambiar)\b/i.test(input);
+  if (exact) {
+    checked.push('exact-anchors');
+    for (const anchor of exactAnchors(input)) if (!output.includes(anchor)) issues.push(`missing ${anchor}`);
+    const negated = /\b(?:no|nunca|jam[aá]s|sin|not|never|without|do not|don't)\b/i.test(input);
+    if (negated && !/\b(?:no|nunca|jam[aá]s|sin|not|never|without|do not|don't|did not|didn't)\b/i.test(output)) issues.push('missing negation');
+  }
+
+  return { ok: issues.length === 0, checked, issues: unique(issues).slice(0, 12) };
+}

package/src/modules/ash.mjs

@@ -23,7 +23,7 @@ export default defineModule({
   name: 'Ash',
   vendor: 'MADRE',
   version: '1.0.0',
-  summary: 'Asks every agent for compact prose. The rest of the economy is always on: the briefing carries only what a turn can use, what never changes is read first so a cache can match it, and the transcript holds still instead of sliding.',
+  summary: 'Asks every agent for compact prose without altering what you write. MADRE shows each turn\'s input, output and cache use; savings depend on the agent, task and cache, so no fixed percentage is promised.',
   creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
   card: 'ash',
   async status(ctx) {

package/src/modules/choices.mjs

@@ -0,0 +1,34 @@
+// Choices: letting an agent put a decision to the human instead of taking it.
+//
+// An agent that has to pick between three or more real options has two honest ways out: name the
+// one it recommends, or hand the choice over. The second had no shape in this room — it came out
+// as a paragraph listing possibilities, which the human then had to answer in prose. This gives
+// it a shape: a fenced block the room turns into buttons.
+//
+// It has a switch because it is not free. The instruction that teaches an agent the block is
+// written into every prompt while this is on, and MADRE measures it like every other block: it
+// shows up as `choices` in the economy's breakdown, at about 135 tokens a turn. A capability
+// whose cost cannot be seen is a capability nobody can decide against.
+//
+// Nothing it produces runs. Pressing an option writes it into the composer; sending it is still
+// the human's, as is ignoring the question entirely.
+
+import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+
+export default defineModule({
+  id: 'choices',
+  configKey: 'choices',
+  name: 'Choices',
+  vendor: 'MADRE',
+  version: '1.0.0',
+  summary: 'Lets an agent hand a decision back to you as buttons instead of a paragraph, when the answer turns on three or more real options. Costs about 135 tokens of instruction per turn while it is on, counted in the economy like every other block.',
+  creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? t('on · agents may ask you to choose') : t('off · agents answer in prose') },
+      install: { display: ctx.settings.enabled ? 'stop offering choices' : 'let agents offer choices', platforms: [] },
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setChoices(enabled); return null; },
+});

package/src/modules/correo.mjs

@@ -0,0 +1,107 @@
+// CORREO: MADRE's first connector. It gives a turn one tool, send_email, that hands a message to
+// the human's own mail account over SMTP+TLS, with the human's own app password.
+//
+// Three things are true of this module that are not true of any other, and they are the reason
+// the connector door took three pieces of groundwork before it could be opened:
+//
+//   · It holds a secret. `ctx.vault` is this module's own corner of `src/vault.mjs`; the password
+//     only ever leaves it into the environment of the server process spawned for one turn.
+//   · It declares where it reaches. `reaches` puts the mail host in the outbound log as something
+//     this module vouched for, instead of as an address nothing here declares.
+//   · What it does does not come back. `sends: ['send_email']` makes the room withhold the tool
+//     below #4 AIRLOCK — the core enforces it, not this file's good intentions.
+//
+// Sending only. Reading mail is a separate decision (D-003's second half in docs/CONECTORES.md):
+// IMAP is a different protocol with a different shape of risk, and everything it brings into the
+// room travels to whichever model the agent runs on.
+
+import { fileURLToPath } from 'node:url';
+import { declareDestinations } from '../outbound.mjs';
+import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+import { REACHES, reachesFor } from '../mcp/smtp-server.mjs';
+import { validAddress } from '../smtp.mjs';
+
+const SERVER = fileURLToPath(new URL('../mcp/smtp-server.mjs', import.meta.url));
+const SECRET = 'app-password';
+
+export default defineModule({
+  id: 'correo',
+  configKey: 'correo',
+  name: 'CORREO',
+  vendor: 'MADRE · SMTP',
+  version: '1.0.0',
+  summary: 'Lets an agent send one plain-text email from your own account, through your provider, with an app password you keep here. Sending is only offered in #4 AIRLOCK, and a sent message cannot be undone.',
+  creates: ['nothing in the project', 'an entry in ~/.pulse/config.json', 'your app password in MADRE’s vault, 0600', 'an MCP server per turn, started and stopped by the room'],
+  requires: ['an app password from your mail provider (Gmail: Account → Security → 2-Step Verification → App passwords)', 'the turn must be in #4 AIRLOCK: below that the tool is not offered at all'],
+  settings: { enabled: false, from: '', fromName: '', host: 'smtp.gmail.com', allow: '' },
+  controls: [
+    { key: 'from', label: 'FROM', type: 'text', note: 'The address messages are sent from. It is also the account that signs in, unless your provider says otherwise.' },
+    { key: 'fromName', label: 'NAME', type: 'text', note: 'The display name beside the address. Optional.' },
+    { key: 'host', label: 'SMTP HOST', type: 'text', note: 'smtp.gmail.com for Gmail. Always port 465, TLS from the first byte.' },
+    { key: 'allow', label: 'ONLY TO', type: 'text', note: 'Addresses or @domains an agent may write to, separated by commas. Empty means anyone — narrow it if you want a floor under a mistake.' },
+  ],
+  secrets: [{
+    name: SECRET,
+    label: 'APP PASSWORD',
+    note: 'Not your account password. A 16-character app password, which you can revoke from your provider without touching anything else.',
+    where: 'https://myaccount.google.com/apppasswords',
+  }],
+  // The default, declared at load. A human who points CORREO at another provider re-declares it
+  // below under the same id, so the log never vouches for a host this module stopped using.
+  reaches: REACHES,
+
+  async onSettings(ctx, settings) { declareDestinations('correo', reachesFor(String(settings.host ?? '').trim() || 'smtp.gmail.com')); },
+
+  async status(ctx) {
+    const held = await ctx.vault.held();
+    const hasSecret = held.some((one) => one.name === SECRET);
+    const from = String(ctx.settings.from ?? '').trim();
+    const problems = [];
+    if (!from) problems.push('No sending address yet: put the account in FROM.');
+    else if (!validAddress(from)) problems.push(`FROM is not an address: ${from}`);
+    if (!hasSecret) problems.push('No app password yet. Gmail: Account → Security → 2-Step Verification → App passwords, then paste it above.');
+    const ready = !problems.length;
+    const allow = String(ctx.settings.allow ?? '').trim();
+    return {
+      status: {
+        installed: Boolean(ctx.settings.enabled),
+        detail: !ctx.settings.enabled ? (ready ? t('off · ready') : t('off')) : ready ? `${t('on')} · ${from}${allow ? ` · ${t('only to')} ${allow}` : ''}` : t('on · not configured'),
+      },
+      preflight: { ok: ready, problems },
+      install: { display: ctx.settings.enabled ? 'disable CORREO' : 'enable CORREO (config.json)', platforms: ['claude', 'codex', 'gemini', 'opencode'] },
+    };
+  },
+
+  // The tool, for one turn. Everything that could be missing is checked here rather than left for
+  // the model to discover: a tool that is offered and then always fails is worse than no tool.
+  async toolsForTurn(ctx) {
+    const from = String(ctx.settings.from ?? '').trim();
+    if (!validAddress(from)) return [];
+    const password = await ctx.vault.get(SECRET);
+    if (!password) return [];
+    const host = String(ctx.settings.host ?? '').trim() || 'smtp.gmail.com';
+    const allow = String(ctx.settings.allow ?? '').trim();
+    declareDestinations('correo', reachesFor(host));
+    return [{
+      name: 'correo',
+      command: process.execPath,
+      args: [SERVER],
+      env: {
+        PULSE_SMTP_FROM: from,
+        PULSE_SMTP_FROM_NAME: String(ctx.settings.fromName ?? '').trim(),
+        PULSE_SMTP_HOST: host,
+        PULSE_SMTP_PASSWORD: password,
+        ...(allow ? { PULSE_SMTP_ALLOW: allow } : {}),
+        // So the one call that carries somebody's words out of this machine lands in the same
+        // log as everything else. A TLS socket is not fetch, so the server writes its own line.
+        ...(ctx.env?.PULSE_OUTBOUND_LOG ? { PULSE_OUTBOUND_LOG: ctx.env.PULSE_OUTBOUND_LOG } : {}),
+        ...(ctx.env?.PULSE_SMTP_FAKE ? { PULSE_SMTP_FAKE: ctx.env.PULSE_SMTP_FAKE, ...(ctx.env.PULSE_SMTP_FAKE_FILE ? { PULSE_SMTP_FAKE_FILE: ctx.env.PULSE_SMTP_FAKE_FILE } : {}) } : {}),
+      },
+      tools: ['send_email'],
+      // What makes the room hold this back below #4. Declared here, enforced in modules/index.mjs.
+      sends: ['send_email'],
+      brief: `You can send one plain-text email from ${from} with the MCP tool send_email (server correo), through ${host}. It is the human's own account and their name on it, and a sent message cannot be recalled: say in one line who it goes to and what it says, then send.${allow ? ` Only these recipients are allowed: ${allow}.` : ''}`,
+    }];
+  },
+});