toolroll 0.9.92 → 0.9.94

package/dist/memory-cli.js

@@ -3,7 +3,9 @@
  * record who did them. Nothing here starts a model. */
 import { envelopeJson } from './envelope.js';
 import { decisionHistory, getDecision, listDecisions, recordDecision, retireDecision, searchMemory } from './project-memory.js';
-import { decideProposal, defaultAnalyzer, listProposals, memoryStatus, runMemoryPass } from './memory-pass.js';
+import { decideProposal, defaultAnalyzer, defaultTidyAnalyzer, listProposals, memoryStatus, runMemoryPass } from './memory-pass.js';
+import { afterwardsWords, noteAfterwards, NOTE_SURFACE } from './lesson-notes.js';
+import { decideTidy, listTidy, proposeTidy, restoreDecision, restoreLesson, restoreReference, unmergeDecisions } from './memory-tidy.js';
 const flags = [
     { name: 'repo', takesValue: true, meaning: 'admitted project checkout root' },
     { name: 'why', takesValue: true, meaning: 'the reason behind a decision' },
@@ -14,6 +16,9 @@ const flags = [
     { name: 'json', takesValue: false, meaning: 'versioned structured response' },
     { name: 'db', takesValue: true, meaning: 'local Toolroll database' },
     { name: 'decision', takesValue: true, meaning: 'accept or reject, for memory apply' },
+    { name: 'claim', takesValue: true, meaning: 'your own words for a lesson note or a clean-up, for memory apply' },
+    { name: 'choice', takesValue: true, meaning: 'what a clean-up does: keep:<id>, both or new; rewrite or retire; for a restore, retire or keep' },
+    { name: 'revision', takesValue: true, meaning: 'the saved knowledge version a reference comes back from, for memory restore' },
     { name: 'sessions', takesValue: true, meaning: 'at most this many newest sessions for one pass (default 100)' },
     { name: 'no-local', takesValue: false, meaning: 'read only the plane\'s own transcripts, not local Claude Code or Codex session files' },
 ];
@@ -25,17 +30,24 @@ export const MEMORY_DESCRIPTORS = [
     { action: 'retire', synopsis: 'retire a decision that no longer holds: memory retire <id> --reason "<why>"', mutation: 'unkeyed', takesQuery: true, flags, audience: 'operator' },
     { action: 'propose', synopsis: 'the backward pass: read recent sessions, keep a ledger of evidenced gaps, propose a few edits (writes nothing to memory)', mutation: 'unkeyed', takesQuery: false, flags },
     { action: 'review', synopsis: 'list pending memory proposals with their evidence', mutation: 'none', takesQuery: false, flags },
-    { action: 'apply', synopsis: 'decide one proposal: memory apply <id> --decision accept|reject — the only writer', mutation: 'unkeyed', takesQuery: true, flags, audience: 'operator' },
+    { action: 'apply', synopsis: 'decide one proposal: memory apply <id> --decision accept|reject [--claim "<your words>"] — the only writer', mutation: 'unkeyed', takesQuery: true, flags, audience: 'operator' },
+    { action: 'tidy', synopsis: 'propose retiring, merging or settling memory entries; a person accepts each (writes nothing to memory)', mutation: 'unkeyed', takesQuery: false, flags, audience: 'operator' },
+    { action: 'restore', synopsis: 'bring back a decision: memory restore <id>, lesson:<id>, or reference:<id> --revision <version>', mutation: 'unkeyed', takesQuery: true, flags, audience: 'operator' },
+    { action: 'unmerge', synopsis: 'undo a merge of decisions: memory unmerge <merge>', mutation: 'unkeyed', takesQuery: true, flags, audience: 'operator' },
     { action: 'status', synopsis: 'surface version, instruction budget, sessions analysed, open gaps and pending proposals', mutation: 'none', takesQuery: false, flags },
 ];
 const line = (d) => `#${d.id} ${d.claim} — ${d.decidedBy}, ${d.decidedAt.slice(0, 10)}${d.status === 'active' ? '' : ` (${d.status})`}`;
+const TIDY_WORDS = { retire: 'Retire unused', merge: 'Merge duplicates', contradiction: 'Contradiction', 'note-failing': 'Note keeps failing', restore: 'Restore', unmerge: 'Undo merge' };
+const itemWords = (p, item) => item.kind === 'decision' ? `decision #${item.id} (version ${item.revision}, ${item.status}) ${p.titles[`decision:${item.id}`] ?? ''}`.trim()
+    : item.kind === 'lesson' ? `lesson #${item.id} (version ${item.version})` : `reference ${item.id} (knowledge version ${item.revision})`;
+const tidyLine = (p) => `t${p.id} ${TIDY_WORDS[p.kind]}${p.status === 'pending' ? '' : ` (${p.status})`}\n  ${p.rationale}${p.afterText ? `\n  → ${p.afterText}` : ''}\n${p.items.map(item => `  - ${itemWords(p, item)}`).join('\n')}`;
 export async function runMemoryCommand(positional, options, context) {
     const action = positional[0];
     const command = action ? `memory ${action}` : 'memory';
     const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : message); return reason === 'usage' ? 2 : 1; };
     const ok = (result, lines) => { context.write(context.json ? envelopeJson({ ok: true, command, ...result }) : lines.join('\n')); return 0; };
     if (!MEMORY_DESCRIPTORS.some(d => d.action === action))
-        return fail('usage', 'Use memory search <query> | decisions | show <id> | decide "<choice>" --why "<reason>" | retire <id> --reason "<why>" | propose | review | apply <id> --decision accept|reject | status, with --repo PATH.');
+        return fail('usage', 'Use memory search <query> | decisions | show <id> | decide "<choice>" --why "<reason>" | retire <id> --reason "<why>" | tidy | restore <id> | unmerge <id> | propose | review | apply <id> --decision accept|reject | status, with --repo PATH.');
     if (context.actor === null)
         return fail('unauthenticated', 'Sign in first: the remembered local login drives memory commands.');
     const text = (key) => { const v = options.get(key); return typeof v === 'string' ? v : null; };
@@ -51,6 +63,7 @@ export async function runMemoryCommand(positional, options, context) {
         return fail('usage', 'Use --repo with the project checkout root.');
     if (!context.repos.includes(repo))
         return fail('not-found', 'That project is outside your access.');
+    const expanded = (done, words) => done.restored ? ok({ done }, [words]) : ok({ done }, [`Nothing changed yet: this reaches past what replaced it. Review t${done.proposal} (memory review) and apply it with --choice retire or --choice keep.`]);
     try {
         if (action === 'decisions') {
             const decisions = listDecisions(context.store, repo, context.actor, { status: options.has('all') ? 'all' : 'active', limit: 100 });
@@ -64,7 +77,8 @@ export async function runMemoryCommand(positional, options, context) {
             if (decision === null)
                 return fail('not-found', 'No such decision in this project.');
             const history = decisionHistory(context.store, repo, context.actor, id);
-            return ok({ decision, history }, [line(decision), `Why: ${decision.why}`, `Source: ${decision.sourceKind}${decision.sourceRef ? ` · ${decision.sourceRef}` : ''}`, ...history.map(h => `  v${h.revision} ${h.action} by ${h.actor} at ${h.at.slice(0, 16).replace('T', ' ')}`)]);
+            const after = noteAfterwards(context.store, decision);
+            return ok({ decision, history, ...(after === null ? {} : { afterwards: after }) }, [line(decision), `Why: ${decision.why}`, `Source: ${decision.sourceKind}${decision.sourceRef ? ` · ${decision.sourceRef}` : ''}`, ...history.map(h => `  v${h.revision} ${h.action} by ${h.actor} at ${h.at.slice(0, 16).replace('T', ' ')}`), ...(after === null ? [] : [afterwardsWords(after)])]);
         }
         if (action === 'decide') {
             const claim = positional.slice(1).join(' ').trim(), why = text('why') ?? '';
@@ -76,12 +90,44 @@ export async function runMemoryCommand(positional, options, context) {
         }
         if (action === 'status') {
             const status = memoryStatus(context.store, repo, context.actor);
-            return ok({ status }, [`Surface ${status.surface} · instructions ${status.instructionBytes}/${status.budgetBytes} bytes`, `Sessions: ${status.sessions.total} seen, ${status.sessions.analyzed} analysed, ${status.sessions.failed} failed`, `Open gaps: ${status.openGaps} · pending proposals: ${status.pending}`]);
+            return ok({ status }, [`Surface ${status.surface} · instructions ${status.instructionBytes}/${status.budgetBytes} bytes`, `Sessions: ${status.sessions.total} seen, ${status.sessions.analyzed} analysed, ${status.sessions.failed} failed`, `Open gaps: ${status.openGaps} · pending proposals: ${status.pending}`, ...status.included.map(one => `${one.kind} ${one.title}: ${one.words}`), ...(status.included.length === 0 ? [] : ['Last included is counted in runs; lead chats aren\'t counted.'])]);
         }
-        const proposalLine = (p) => `#${p.id} ${p.kind} · ${p.title} (${p.sessions} sessions${p.status === 'pending' ? '' : `, ${p.status}`})\n  ${p.rationale}${p.afterText ? `\n  → ${p.afterText}` : ''}${p.beforeText ? `\n  ← ${p.beforeText}` : ''}${p.evidence.map(e => `\n  "${e.quote.slice(0, 160)}" — ${e.session.split(':')[0]}`).join('')}`;
+        const proposalLine = (p) => p.surface === NOTE_SURFACE ? `#${p.id} ${p.title}${p.status === 'pending' ? '' : ` (${p.status})`}\n  ${p.rationale}\n  Draft: ${p.afterText}\n  Accept with your own words: memory apply ${p.id} --decision accept --claim "…"` : `#${p.id} ${p.kind} · ${p.title} (${p.sessions} sessions${p.status === 'pending' ? '' : `, ${p.status}`})\n  ${p.rationale}${p.afterText ? `\n  → ${p.afterText}` : ''}${p.beforeText ? `\n  ← ${p.beforeText}` : ''}${p.evidence.map(e => `\n  "${e.quote.slice(0, 160)}" — ${e.session.split(':')[0]}`).join('')}`;
+        const proof = 'cli-login';
         if (action === 'review') {
             const proposals = listProposals(context.store, repo, options.has('all') ? 'all' : 'pending');
-            return ok({ proposals }, proposals.length === 0 ? ['No proposals waiting. Run memory propose after more sessions.'] : proposals.map(proposalLine));
+            const cleanups = listTidy(context.store, repo, options.has('all') ? 'all' : 'pending');
+            return ok({ proposals, cleanups }, proposals.length + cleanups.length === 0 ? ['No proposals waiting. Run memory propose after more sessions.'] : [...proposals.map(proposalLine), ...cleanups.map(tidyLine)]);
+        }
+        if (action === 'tidy') {
+            const analyzer = context.tidyAnalyzer ?? defaultTidyAnalyzer(context.store, { ...(context.configDir === undefined ? {} : { configDir: context.configDir }) });
+            const report = await proposeTidy(context.store, { repo, actor: context.actor, analyzer }, context.now);
+            return ok({ report }, [`New clean-up suggestions: ${report.made}`, ...(report.problem === null ? [] : [report.problem]), 'Review them with memory review.']);
+        }
+        if (action === 'restore') {
+            const target = positional[1] ?? '';
+            const lesson = /^lesson:(\d+)$/.exec(target), reference = /^reference:([a-f0-9]{20})$/.exec(target);
+            if (lesson !== null) {
+                restoreLesson(context.store, context.evidenceRoot ?? '', { repo, actor: context.actor, id: Number(lesson[1]), proof }, context.now);
+                return ok({ lesson: Number(lesson[1]) }, [`Lesson #${lesson[1]} is in use again.`]);
+            }
+            if (reference !== null) {
+                const revision = Number(text('revision'));
+                if (!Number.isSafeInteger(revision) || revision < 1)
+                    return fail('usage', 'memory restore reference:<id> --revision <saved version>');
+                restoreReference(context.store, { repo, actor: context.actor, id: reference[1], fromRevision: revision, proof }, context.now);
+                return ok({ reference: reference[1] }, ['Reference added back as a new version.']);
+            }
+            const id = Number(target);
+            if (!Number.isSafeInteger(id) || id < 1)
+                return fail('usage', 'memory restore <decision id> | lesson:<id> | reference:<id> --revision <version>');
+            return expanded(restoreDecision(context.store, { repo, actor: context.actor, id, proof }, context.now), `Restored decision #${id}.`);
+        }
+        if (action === 'unmerge') {
+            const merge = Number(positional[1]);
+            if (!Number.isSafeInteger(merge) || merge < 1)
+                return fail('usage', 'memory unmerge <merge id>');
+            return expanded(unmergeDecisions(context.store, { repo, actor: context.actor, merge, proof }, context.now), `Undid merge ${merge}.`);
         }
         if (action === 'propose') {
             const sessions = text('sessions');
@@ -93,10 +139,17 @@ export async function runMemoryCommand(positional, options, context) {
             return ok({ report }, [`Sessions: ${report.sessions} found, ${report.analyzed} analysed now, ${report.cached} already analysed, ${report.failed} failed`, `Open gaps: ${report.gaps} · new proposals: ${report.proposals}`, ...report.problems.slice(0, 5).map(p => `  problem: ${p}`), report.proposals > 0 ? 'Review them with memory review, then memory apply <id> --decision accept|reject.' : 'Nothing to propose yet: a gap needs the same mistake in two distinct sessions.']);
         }
         if (action === 'apply') {
-            const id = Number(positional[1]), decision = text('decision');
+            const cleanup = /^t(\d+)$/.exec(positional[1] ?? '');
+            const id = cleanup === null ? Number(positional[1]) : Number(cleanup[1]), decision = text('decision');
             if (!Number.isSafeInteger(id) || id < 1 || (decision !== 'accept' && decision !== 'reject'))
                 return fail('usage', 'memory apply <proposal id> --decision accept|reject');
-            const proposal = decideProposal(context.store, { repo, actor: context.actor, id, decision }, context.now);
+            if (cleanup !== null) {
+                const choice = text('choice'), said = text('claim'), why = text('why');
+                const decided = decideTidy(context.store, context.evidenceRoot ?? '', { repo, actor: context.actor, id, decision, proof, ...(choice === null ? {} : { choice }), ...(said === null ? {} : { claim: said }), ...(why === null ? {} : { why }) }, context.now);
+                return ok({ cleanup: decided }, [`${decision === 'accept' ? 'Applied' : 'Rejected'} ${tidyLine(decided)}`]);
+            }
+            const claim = text('claim');
+            const proposal = decideProposal(context.store, { repo, actor: context.actor, id, decision, ...(claim === null ? {} : { claim }) }, context.now);
             return ok({ proposal }, [`${decision === 'accept' ? 'Applied' : 'Rejected'} ${proposalLine(proposal)}`]);
         }
         const id = Number(positional[1]), reason = text('reason') ?? '';

package/dist/memory-pass.d.ts

@@ -1,5 +1,6 @@
 import type { Store } from './store.js';
 import { performSubscriptionLeadRequest } from './subscription-chat.js';
+import { type TidyAnalyzer } from './memory-tidy.js';
 import { type MemoryProposal, type Verdict } from './contracts/memory-pass.js';
 export type { MemoryProposal, Verdict };
 /** One session's trace, in characters (TEXT_LIMITS.memoryTrace). */
@@ -68,6 +69,14 @@ export declare function defaultAnalyzer(store: Store, options: {
     timeoutMs?: number;
     runner?: Parameters<typeof performSubscriptionLeadRequest>[1];
 }): MemoryAnalyzer;
+/** The clean-up's question to the chat model, asked only on a person's request (memory-tidy.ts proposeTidy). */
+export declare function defaultTidyAnalyzer(store: Store, options?: {
+    env?: NodeJS.ProcessEnv;
+    configDir?: string;
+    fetcher?: typeof fetch;
+    runner?: Parameters<typeof performSubscriptionLeadRequest>[1];
+    timeoutMs?: number;
+}): TidyAnalyzer;
 /**
  * Read the analyser's answer with the tolerant parse-side schema, then keep only claims whose quote
  * is really in the trace and, for an instruction's effect, whose id is on the surface audited.
@@ -120,6 +129,7 @@ export declare function decideProposal(store: Store, args: {
     actor: string;
     id: number;
     decision: 'accept' | 'reject';
+    claim?: string;
 }, now?: Date): MemoryProposal;
 export declare function memoryStatus(store: Store, repo: string, actor: string): {
     surface: string;
@@ -132,4 +142,10 @@ export declare function memoryStatus(store: Store, repo: string, actor: string):
     };
     openGaps: number;
     pending: number;
+    included: {
+        kind: string;
+        item: string;
+        title: string;
+        words: string;
+    }[];
 };

package/dist/memory-pass.js

@@ -21,6 +21,10 @@ import { listDecisions, recordDecision, refuseLeadMemoryWrite } from './project-
 import { composeLeadRequest, performLeadRequest, isDirectChatProvider, CHAT_KEY_ENV } from './converse.js';
 import { performSubscriptionLeadRequest } from './subscription-chat.js';
 import { TEXT_LIMITS } from './text-limits.js';
+import { lastIncludedWords, memoryUseOf } from './memory-use.js';
+import { lessonNoteOf, lessonNoteSourceRef, NOTE_SURFACE, watchNote } from './lesson-notes.js';
+import { currentLocalOwner } from './local-owner.js';
+import { CONTRADICTION_SCHEMA } from './memory-tidy.js';
 import { contractError, parseContract } from './contracts/contract.js';
 import { MEMORY_VERDICT_MODEL_SCHEMA, MEMORY_VERDICT_VERSION, memoryEvidenceSchema, memoryProposalSchema, memoryVerdictReadSchema, readSavedVerdict, savedVerdictSchema } from './contracts/memory-pass.js';
 /** One session's trace, in characters (TEXT_LIMITS.memoryTrace). */
@@ -220,6 +224,36 @@ export function defaultAnalyzer(store, options) {
         return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
     };
 }
+/** The clean-up's question to the chat model, asked only on a person's request (memory-tidy.ts proposeTidy). */
+export function defaultTidyAnalyzer(store, options = {}) {
+    return async (input) => {
+        if (inEvalWorld())
+            return { ok: false, problem: 'Clean up makes no provider call in an eval world.' };
+        const config = store.getChatConfig();
+        if (config === null)
+            return { ok: false, problem: 'Chat is not configured, so contradictions were not looked for.' };
+        const history = [{ role: 'operator', text: 'Read the decisions above and return the JSON object.' }];
+        if (isDirectChatProvider(config.provider)) {
+            const env = options.env ?? process.env;
+            let key = env[CHAT_KEY_ENV[config.provider]] ?? '';
+            if (!key && options.configDir !== undefined) {
+                try {
+                    key = readFileSync(join(options.configDir, `chat-key-${config.provider}`), 'utf8').trim();
+                }
+                catch {
+                    key = '';
+                }
+            }
+            if (!key)
+                return { ok: false, problem: `No ${config.provider} key is available, so contradictions were not looked for.` };
+            const request = composeLeadRequest({ provider: config.provider, model: config.model, key, system: input.system, dataDocument: input.data, history, tools: [] });
+            const answer = await performLeadRequest(request, config.provider, AbortSignal.timeout(options.timeoutMs ?? 120_000), options.fetcher);
+            return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
+        }
+        const answer = await performSubscriptionLeadRequest({ provider: config.provider, model: config.model, system: input.system, dataDocument: input.data, history, tools: [], outputSchema: CONTRADICTION_SCHEMA, timeoutMs: options.timeoutMs ?? 180_000 }, options.runner);
+        return answer.ok ? { ok: true, text: answer.answer.text } : { ok: false, problem: answer.problem };
+    };
+}
 const UNREADABLE = 'The analysis was not a readable verdict.';
 /**
  * Read the analyser's answer with the tolerant parse-side schema, then keep only claims whose quote
@@ -336,7 +370,8 @@ export function synthesizeProposals(store, repo, actor, surface, now = new Date(
     const budgetLeft = INSTRUCTION_BUDGET_BYTES - Buffer.byteLength(view.knowledge.instructions);
     let made = 0;
     store.transact(() => {
-        store.handle.prepare("UPDATE memory_proposal SET status='stale' WHERE repo=? AND status='pending' AND surface<>?").run(repo, surface.version);
+        // A lesson note is bound to its own recorded facts, not to the surface.
+        store.handle.prepare("UPDATE memory_proposal SET status='stale' WHERE repo=? AND status='pending' AND surface<>? AND surface<>?").run(repo, surface.version, NOTE_SURFACE);
         const pendingFingerprints = new Set(store.handle.prepare("SELECT fingerprint FROM memory_proposal WHERE repo=? AND status='pending'").all(repo).map(row => String(row['fingerprint'])));
         const rejected = new Map(store.handle.prepare('SELECT fingerprint, sessions FROM memory_rejection WHERE repo=?').all(repo).map(row => [String(row['fingerprint']), Number(row['sessions'])]));
         const consider = (kind, fingerprint, title, rationale, beforeText, afterText, evidence) => {
@@ -401,6 +436,7 @@ export function listProposals(store, repo, status = 'pending') {
 export function decideProposal(store, args, now = new Date()) {
     refuseLeadMemoryWrite();
     return store.transact(() => {
+        refuseLeadMemoryWrite();
         // A person who may change this project's memory, read inside the write (a revoked account or lost access refuses).
         if (!store.accountCanAccess(args.actor, args.repo) || store.accountOf(args.actor)?.role !== 'approver')
             throw Error('Project memory is outside your access.');
@@ -410,8 +446,13 @@ export function decideProposal(store, args, now = new Date()) {
         const proposal = proposalOf(row);
         if (proposal.status !== 'pending')
             throw Error('That proposal was already decided.');
+        const note = lessonNoteOf(store, proposal.id);
+        // The laptop's local owner may decide lesson notes and clean-ups, nothing else here (D3): the act says which.
+        const local = currentLocalOwner();
+        if (local !== null && (note === null || local.act !== 'memory-review'))
+            throw Error('Sign in with your password to do this.');
         const surface = memorySurface(store, args.repo, args.actor);
-        if (surface.version !== proposal.surface) {
+        if (note === null && surface.version !== proposal.surface) {
             store.handle.prepare("UPDATE memory_proposal SET status='stale' WHERE id=?").run(proposal.id);
             throw Error('Project memory changed since this was proposed. Run the pass again.');
         }
@@ -419,6 +460,14 @@ export function decideProposal(store, args, now = new Date()) {
             store.handle.prepare('INSERT INTO memory_rejection(repo,fingerprint,rejected_at,rejected_by,sessions) VALUES (?,?,?,?,?) ON CONFLICT(repo,fingerprint) DO UPDATE SET rejected_at=excluded.rejected_at, rejected_by=excluded.rejected_by, sessions=excluded.sessions')
                 .run(args.repo, proposal.fingerprint, now.toISOString(), args.actor, proposal.sessions);
         }
+        else if (note !== null) {
+            // A person's words, not the draft: "failed then passed" is what Toolroll recorded; what it means is theirs to say.
+            const claim = (args.claim ?? '').trim();
+            if (claim === '' || claim === proposal.afterText.trim())
+                throw Error('Write the note in your own words before accepting it.');
+            recordDecision(store, { repo: args.repo, actor: args.actor, draft: { claim, why: clip(proposal.rationale, 1500), sourceKind: 'result', sourceRef: lessonNoteSourceRef(proposal.id) } }, now);
+            watchNote(store, { repo: args.repo, proposal: proposal.id, identities: note.identities, now });
+        }
         else {
             const view = knowledgeView(store, args.repo, args.actor);
             if (proposal.kind === 'instruction-add')
@@ -441,5 +490,20 @@ export function memoryStatus(store, repo, actor) {
     return { surface: surface.version, instructionBytes: Buffer.byteLength(view.knowledge.instructions), budgetBytes: INSTRUCTION_BUDGET_BYTES,
         sessions: { total: Number(counts['total'] ?? 0), analyzed: Number(counts['analyzed'] ?? 0), failed: Number(counts['failed'] ?? 0) },
         openGaps: Number(store.handle.prepare('SELECT COUNT(*) AS n FROM memory_gap WHERE repo=? AND retired_at IS NULL').get(repo)?.['n'] ?? 0),
-        pending: Number(store.handle.prepare("SELECT COUNT(*) AS n FROM memory_proposal WHERE repo=? AND status='pending'").get(repo)?.['n'] ?? 0) };
+        pending: Number(store.handle.prepare("SELECT COUNT(*) AS n FROM memory_proposal WHERE repo=? AND status='pending'").get(repo)?.['n'] ?? 0),
+        included: includedLines(store, repo, actor, view.knowledge.references) };
+}
+/** "Last included" for every decision, reference and adopted lesson, in the order they're listed elsewhere. */
+function includedLines(store, repo, actor, references) {
+    const use = memoryUseOf(store, repo);
+    const line = (kind, item, title) => ({ kind, item, title, words: lastIncludedWords(use.get(`${kind}:${item}`)) });
+    const lessons = store.handle.prepare("SELECT id, payload FROM project_lesson WHERE repo=? AND status='adopted' ORDER BY id DESC LIMIT 50").all(repo).flatMap(row => {
+        try {
+            return [line('lesson', String(row['id']), clip(String(JSON.parse(String(row['payload'])).observation ?? ''), 80))];
+        }
+        catch {
+            return [];
+        }
+    });
+    return [...listDecisions(store, repo, actor, { limit: 50 }).map(d => line('decision', String(d.id), clip(d.claim, 80))), ...references.map(ref => line('reference', ref.id, clip(ref.title, 80))), ...lessons];
 }

package/dist/memory-tidy.d.ts

@@ -0,0 +1,181 @@
+import { type Decision } from "./project-memory.js";
+import type { Store } from "./store.js";
+export declare const UNUSED_DAYS = 60, UNUSED_RUNS = 20, FAILING_NOTE = 3, TIDY_MIN_ENTRIES = 10;
+export declare const TIDY_EVERY_MS: number, TIDY_QUIET_MS = 86400000;
+/** What a stale proposal says. */
+export declare const TIDY_STALE = "Changed since proposed. Run Clean up again.";
+export type TidyItem = {
+    kind: "decision";
+    id: number;
+    revision: number;
+    status: string;
+    sha: string;
+} | {
+    kind: "reference";
+    id: string;
+    revision: number;
+    sha: string;
+} | {
+    kind: "lesson";
+    id: number;
+    version: number;
+    sha: string;
+};
+export type TidyKind = "retire" | "merge" | "contradiction" | "note-failing" | "restore" | "unmerge";
+export type TidyProposal = {
+    id: number;
+    repo: string;
+    kind: TidyKind;
+    items: TidyItem[];
+    afterText: string | null;
+    rationale: string;
+    evidence: Record<string, unknown>;
+    source: string;
+    status: string;
+    createdAt: string;
+    decidedBy: string | null;
+    titles: Record<string, string>;
+};
+export declare function listTidy(store: Store, repo: string, status?: "pending" | "all"): TidyProposal[];
+/**
+ * The scheduled pass: deterministic, no analyzer in reach. Runs when the project has been quiet for a day, at most
+ * weekly, with at least 10 entries. Proposes only.
+ */
+export declare function scheduledTidy(store: Store, repo: string, now: Date): number;
+export type TidyAnalyzer = (input: {
+    system: string;
+    data: string;
+}) => Promise<{
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    problem: string;
+}>;
+export declare const CONTRADICTION_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["contradictions"];
+    readonly properties: {
+        readonly contradictions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["a", "b", "why"];
+                readonly properties: {
+                    readonly a: {
+                        readonly type: "integer";
+                    };
+                    readonly b: {
+                        readonly type: "integer";
+                    };
+                    readonly why: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+};
+/** Read a model's pairs: ids of active decisions only, a clean reason, each pair once. Everything else is dropped. */
+export declare function parseContradictions(text: string, active: readonly number[]): {
+    a: number;
+    b: number;
+    why: string;
+}[];
+/** Clean up, on a person's request: the deterministic pass with no quiet gate, and contradictions when an analyzer is given. */
+export declare function proposeTidy(store: Store, args: {
+    repo: string;
+    actor: string;
+    analyzer?: TidyAnalyzer;
+}, now: Date): Promise<{
+    made: number;
+    problem: string | null;
+}>;
+/** Every decision reachable from `id` through ordinary supersession and not-undone merges, transitively (never `id`). */
+export declare function successorChain(store: Store, repo: string, id: number): number[];
+/** The active decisions in `id`'s chain. */
+export declare function activeTail(store: Store, repo: string, id: number): number[];
+/** One new decision from several; each old one superseded with a "merged into" history row; every member listed. */
+export declare function mergeDecisions(store: Store, args: {
+    repo: string;
+    actor: string;
+    ids: readonly number[];
+    claim: string;
+    why: string;
+    proof: string;
+}, now: Date): Decision;
+export type ExpandedChange = {
+    restored: false;
+    proposal: number;
+    items: TidyItem[];
+};
+/**
+ * Restore a retired or superseded decision. With no active tail it goes straight back to active. With one, nothing
+ * changes: a proposal names every affected item, and a person chooses what happens to the tail.
+ */
+export declare function restoreDecision(store: Store, args: {
+    repo: string;
+    actor: string;
+    id: number;
+    proof: string;
+}, now: Date): {
+    restored: true;
+    decision: Decision;
+} | ExpandedChange;
+/**
+ * Undo a merge. Direct only while its successor is active, at the revision recorded at the merge, and not merged on.
+ * Otherwise nothing changes: a proposal names every affected item, the later merge included. A merge already undone is
+ * refused and changes nothing.
+ */
+export declare function unmergeDecisions(store: Store, args: {
+    repo: string;
+    actor: string;
+    merge: number;
+    proof: string;
+}, now: Date): {
+    restored: true;
+    successor: number;
+} | ExpandedChange;
+/** A disabled lesson back in use (re-checks its support, bound to its version and sha). */
+export declare function restoreLesson(store: Store, root: string, args: {
+    repo: string;
+    actor: string;
+    id: number;
+    proof: string;
+}, now: Date): void;
+/** A reference back from history, as a new knowledge revision bound to the current one. */
+export declare function restoreReference(store: Store, args: {
+    repo: string;
+    actor: string;
+    id: string;
+    fromRevision: number;
+    proof: string;
+}, now: Date): void;
+export type TidyDecision = {
+    repo: string;
+    actor: string;
+    id: number;
+    decision: "accept" | "reject";
+    choice?: string;
+    claim?: string;
+    why?: string;
+    proof: string;
+};
+/**
+ * Accept or reject one proposal: the one writer of a proposal's outcome. In one transaction, a person's standing, the
+ * proposal's state and every bound item are re-read; any difference marks it stale and changes nothing.
+ */
+export declare function decideTidy(store: Store, root: string, args: TidyDecision, now: Date): TidyProposal;
+/** Merges that can still be undone, for the page. */
+export declare function undoableMerges(store: Store, repo: string): {
+    merge: number;
+    successor: number;
+    predecessors: number[];
+}[];
+/** Lessons that were disabled and can be used again, for the page. */
+export declare function disabledLessons(store: Store, repo: string): {
+    id: number;
+    observation: string;
+}[];