@wirecat/cli-core 0.498.0 → 0.500.0

package/dist/speech/recognize.js

@@ -31,10 +31,9 @@ export const decodeOgg = async (bytes) => {
     await decoder.ready;
     try {
         const { channelData, sampleRate, samplesDecoded } = await decoder.decodeFile(bytes);
-        const samples = channelData[0];
-        if (!samples || samplesDecoded === 0)
+        if (!channelData[0] || samplesDecoded === 0)
             throw new Error("no Ogg Opus audio in it");
-        return { samples, rate: sampleRate };
+        return channelData.map((samples) => ({ samples, rate: sampleRate }));
     }
     finally {
         decoder.free();
@@ -59,6 +58,43 @@ export const detector = (vadModel) => ({
     debug: 0,
     bufferSizeInSeconds: 30,
 });
+/**
+ * `pcm` as `toModelRate` made it: the detector's sample offsets count its half-second lead, the recording does not.
+ * Each stretch goes to `each` as it is cut, so an hour of speech is never held twice.
+ */
+const cut = (vad, pcm, each) => {
+    // One detector can hear several recordings in a row; nothing of the last may leak into this one.
+    vad.reset();
+    const last = Math.max(0, pcm.length - LEAD);
+    const drain = () => {
+        for (; !vad.isEmpty(); vad.pop()) {
+            const { start, samples } = vad.front();
+            each({
+                start: Math.min(last, Math.max(0, start - LEAD)) / SAMPLE_RATE,
+                end: Math.min(last, Math.max(0, start + samples.length - LEAD)) / SAMPLE_RATE,
+                samples,
+            });
+        }
+    };
+    for (let i = 0; i + WINDOW <= pcm.length; i += WINDOW) {
+        vad.acceptWaveform(pcm.subarray(i, i + WINDOW));
+        drain();
+    }
+    vad.flush();
+    drain();
+};
+/** The voice detector alone, for a recognizer that is not on this machine. */
+export const openSpeechCutter = (vadModel) => {
+    const vad = loadSherpa().createVad(detector(vadModel));
+    return {
+        cut: (pcm) => {
+            const spans = [];
+            cut(vad, pcm, ({ start, end }) => spans.push({ start, end }));
+            return spans;
+        },
+        free: () => vad.free(),
+    };
+};
 /**
  * The model, and a voice detector that cuts the audio at pauses into pieces of at most 20 seconds.
  * The cutting is not optional: five minutes in one piece crash the WebAssembly build (measured).
@@ -107,25 +143,20 @@ export const openRecognizer = (model, path, vadModel) => {
             stream.free();
         }
     };
+    const pieces = (pcm) => {
+        const heard = [];
+        cut(vad, pcm, ({ start, end, samples }) => {
+            const text = piece(samples);
+            if (text)
+                heard.push({ start, end, text });
+        });
+        return heard;
+    };
     return {
-        recognize: (pcm) => {
-            // One recognizer can hear several recordings in a row; nothing of the last may leak into this one.
-            vad.reset();
-            const parts = [];
-            const drain = () => {
-                while (!vad.isEmpty()) {
-                    parts.push(piece(vad.front().samples));
-                    vad.pop();
-                }
-            };
-            for (let i = 0; i + WINDOW <= pcm.length; i += WINDOW) {
-                vad.acceptWaveform(pcm.subarray(i, i + WINDOW));
-                drain();
-            }
-            vad.flush();
-            drain();
-            return parts.filter(Boolean).join(" ");
-        },
+        recognize: (pcm) => pieces(pcm)
+            .map(({ text }) => text)
+            .join(" "),
+        pieces,
         free: () => {
             vad.free();
             engine.free();

package/dist/speech/transcribe.d.ts

@@ -1,18 +1,21 @@
-import { CliError } from "@wirecat/cli-base";
+import { CliError, type KeyringStore } from "@wirecat/cli-base";
 import type { Messenger } from "../cli/messenger/context.js";
 import { type Settings } from "../cli/settings.js";
 import { type MessengerAdapter, type RemoteFile, type Transcript } from "../ports/messenger.js";
 import type { Ffmpeg } from "./decode.js";
 import { type SpeechModel } from "./models.js";
 import type { Recognizer } from "./recognize.js";
-/** `messenger`: its own recognition (Telegram Premium). `local`: a model on this machine. `auto`: the first, then the second. */
-export declare const TRANSCRIBE_WITH: readonly ["auto", "messenger", "local"];
+/**
+ * `messenger`: its own recognition (Telegram Premium). `local`: a model on this machine. `auto`: the first, then the
+ * second. `openai`: OpenAI's API, only when asked by name — `auto` never sends audio off the machine.
+ */
+export declare const TRANSCRIBE_WITH: readonly ["auto", "messenger", "local", "openai"];
 export type TranscribeWith = (typeof TRANSCRIBE_WITH)[number];
 export interface Heard extends Transcript {
     messageId: string;
-    /** The messenger's provider, or `local`. */
+    /** The messenger's provider, `local` or `openai`. */
     via: string;
-    /** The local model, when it was one. */
+    /** The local or OpenAI model, when it was one. */
     model?: string;
 }
 export type OpenRecognizer = (model: SpeechModel, path: (name: string) => string, vadModel: string) => Recognizer;
@@ -24,17 +27,26 @@ export interface Choice {
     /** The local recognizer, where a test hands one in. */
     open?: OpenRecognizer;
     ffmpeg?: Ffmpeg;
+    /** The profile's `transcribeModel` for `openai`, else `gpt-transcribe`. */
+    transcribeModel?: string;
+    apiKey?: string;
+    /** Why nothing can be heard: an unknown `transcribeWith`, or for `openai` no key or a read-only process. */
+    refusal?: CliError;
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    /** The command's own cancel and deadline, for a request that leaves the machine. */
+    signal?: AbortSignal;
 }
 /** A voice note, or an audio file someone sent — an iPhone recording reaches WhatsApp as `audio/mp4`. */
 export declare const isAudioFile: ({ kind, mime }: {
     kind: string;
     mime?: string | undefined;
 }) => boolean;
-/** The flag, then the profile's `transcribeWith` and `speechModel`, then `auto` and the CLI's first model. */
+/** The flag, then the profile's `transcribeWith`, `speechModel` and `transcribeModel`, then `auto` and the CLI's first model. */
 export declare const choose: (messenger: Messenger, settings: Pick<Settings, "configured" | "shared">, flags: {
     local?: boolean;
     model?: string;
-}, env?: NodeJS.ProcessEnv) => Choice;
+    with?: TranscribeWith;
+}, env?: NodeJS.ProcessEnv, keyring?: KeyringStore) => Choice;
 /** Never a download: a model is hundreds of MB, and whether to fetch one is the owner's call. */
 export declare const notDownloaded: (messenger: Messenger, model: SpeechModel) => CliError;
 /**
@@ -43,5 +55,9 @@ export declare const notDownloaded: (messenger: Messenger, model: SpeechModel) =
  * `read` gets the recording once its bytes are all in, for a reference the messenger renewed while they were read.
  */
 export declare const hearOnline: (messenger: Messenger, connection: MessengerAdapter, chat: string, messageId: string, choice: Choice, read?: (file: RemoteFile) => Promise<void>) => Promise<Heard | Uint8Array>;
-/** The local model, on the bytes `hearOnline` fetched. */
-export declare const hearLocally: (bytes: Uint8Array, messageId: string, { model, directory, open, ffmpeg }: Choice) => Promise<Heard>;
+/** The local model, or OpenAI when chosen, on the bytes `hearOnline` fetched. */
+export declare const hearLocally: (bytes: Uint8Array, messageId: string, choice: Choice) => Promise<Heard>;
+/** Where a kept transcript came from, as `Kept` stores it: the messenger's provider, a local model, or `openai:<model>`. */
+export declare const keptSource: (heard: Heard) => string;
+/** The reverse of `keptSource`. */
+export declare const heardVia: (source: string, provider: string) => Pick<Heard, "via" | "model">;

package/dist/speech/transcribe.js

@@ -1,26 +1,52 @@
 import { CliError, isCliError } from "@wirecat/cli-base";
 import { fromFile } from "../cli/settings.js";
+import { embeddingKeys } from "../embeddings/keys.js";
+import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { capability } from "../ports/messenger.js";
 import { typedCommand } from "../runs/scope.js";
 import { installedBytes, isInstalled, megabytes, modelPath, modelsDirectory, vadPath } from "./install.js";
-import { orderedModels, speechModel } from "./models.js";
-/** `messenger`: its own recognition (Telegram Premium). `local`: a model on this machine. `auto`: the first, then the second. */
-export const TRANSCRIBE_WITH = ["auto", "messenger", "local"];
+import { OPENAI_TRANSCRIBE_MODEL, orderedModels, speechModel } from "./models.js";
+/**
+ * `messenger`: its own recognition (Telegram Premium). `local`: a model on this machine. `auto`: the first, then the
+ * second. `openai`: OpenAI's API, only when asked by name — `auto` never sends audio off the machine.
+ */
+export const TRANSCRIBE_WITH = ["auto", "messenger", "local", "openai"];
 /** A recording is read into memory whole; minutes of Opus are a few megabytes. */
 const LARGEST_VOICE = 32 * 1024 * 1024;
 /** A voice note, or an audio file someone sent — an iPhone recording reaches WhatsApp as `audio/mp4`. */
 export const isAudioFile = ({ kind, mime }) => kind === "voice" || kind === "audio" || (mime?.startsWith("audio/") ?? false);
-/** The flag, then the profile's `transcribeWith` and `speechModel`, then `auto` and the CLI's first model. */
-export const choose = (messenger, settings, flags, env = process.env) => {
+/** The flag, then the profile's `transcribeWith`, `speechModel` and `transcribeModel`, then `auto` and the CLI's first model. */
+export const choose = (messenger, settings, flags, env = process.env, keyring) => {
     const model = flags.model ?? fromFile(settings, "speechModel", undefined).value;
+    const chosen = flags.local || flags.model !== undefined
+        ? "local"
+        : (flags.with ?? fromFile(settings, "transcribeWith", "auto").value);
+    // Refused only where something is heard: `models list` reads the same profile for its model alone.
+    const known = TRANSCRIBE_WITH.includes(chosen);
     return {
         directory: modelsDirectory(env),
-        with: flags.local || flags.model !== undefined
-            ? "local"
-            : fromFile(settings, "transcribeWith", "auto").value,
+        with: known ? chosen : "auto",
+        ...(known
+            ? {}
+            : {
+                refusal: new CliError("validation_error", `the profile's transcribeWith is one of ${TRANSCRIBE_WITH.join(", ")}`),
+            }),
         model: model === undefined ? orderedModels(messenger.speechModels)[0] : speechModel(model),
+        transcribeModel: fromFile(settings, "transcribeModel", OPENAI_TRANSCRIBE_MODEL).value,
+        ...(known && chosen === "openai" ? openaiAccess(messenger, env, keyring) : {}),
     };
 };
+const openaiAccess = (messenger, env, keyring) => {
+    const lock = readOnlyLockOf(messenger.app, env);
+    if (lock)
+        return { refusal: readOnlyRefusal(lock, "send audio to OpenAI") };
+    const apiKey = embeddingKeys(messenger.app, env, keyring).read("openai")?.key;
+    return apiKey
+        ? { apiKey }
+        : {
+            refusal: new CliError("authentication_error", `no OpenAI key — \`${typedCommand(messenger.app.command, "models keys set openai")}\`, or OPENAI_API_KEY`, { reason: "transcription.no-key" }),
+        };
+};
 /** Never a download: a model is hundreds of MB, and whether to fetch one is the owner's call. */
 export const notDownloaded = (messenger, model) => new CliError("not_found", `the speech model ${model.id} is not on this machine — the owner downloads it once with ` +
     `\`${typedCommand(messenger.app.command, `models download ${model.id}`)}\` (${megabytes(installedBytes(model))})`, { reason: "model.not-downloaded", model: model.id });
@@ -30,7 +56,9 @@ export const notDownloaded = (messenger, model) => new CliError("not_found", `th
  * `read` gets the recording once its bytes are all in, for a reference the messenger renewed while they were read.
  */
 export const hearOnline = async (messenger, connection, chat, messageId, choice, read) => {
-    if (choice.with !== "local") {
+    if (choice.refusal)
+        throw choice.refusal;
+    if (choice.with === "auto" || choice.with === "messenger") {
         const canAsk = typeof connection.transcribe === "function";
         if (choice.with === "messenger" || canAsk) {
             try {
@@ -44,7 +72,7 @@ export const hearOnline = async (messenger, connection, chat, messageId, choice,
             }
         }
     }
-    if (!isInstalled(choice.model, choice.directory))
+    if (choice.with !== "openai" && !isInstalled(choice.model, choice.directory))
         throw notDownloaded(messenger, choice.model);
     const { files } = await capability(connection, "download", "download attachments")(chat, messageId);
     const voice = files.find(isAudioFile);
@@ -54,11 +82,34 @@ export const hearOnline = async (messenger, connection, chat, messageId, choice,
     await read?.(voice);
     return bytes;
 };
-/** The local model, on the bytes `hearOnline` fetched. */
-export const hearLocally = async (bytes, messageId, { model, directory, open, ffmpeg }) => {
-    const { openRecognizer, toModelRate } = await import("./recognize.js");
+/** The local model, or OpenAI when chosen, on the bytes `hearOnline` fetched. */
+export const hearLocally = async (bytes, messageId, choice) => {
+    const { model, directory, open, ffmpeg } = choice;
     const { decodeAudio } = await import("./decode.js");
     const { samples, rate } = await decodeAudio(bytes, ffmpeg);
+    if (choice.with === "openai") {
+        if (choice.refusal)
+            throw choice.refusal;
+        const { transcribeOpenAI } = await import("./openai.js");
+        const transcribeModel = choice.transcribeModel ?? OPENAI_TRANSCRIBE_MODEL;
+        const pieces = await transcribeOpenAI({ samples, rate }, {
+            apiKey: choice.apiKey ?? "",
+            model: transcribeModel,
+            vadModel: vadPath(directory),
+            // A voice message wants its text, not its turns: one request, and no voice detector needed.
+            bundle: true,
+            ...(choice.fetch ? { fetch: choice.fetch } : {}),
+            ...(choice.signal ? { signal: choice.signal } : {}),
+        });
+        return {
+            messageId,
+            text: pieces.map(({ text }) => text).join(" "),
+            pending: false,
+            via: "openai",
+            model: transcribeModel,
+        };
+    }
+    const { openRecognizer, toModelRate } = await import("./recognize.js");
     const recognizer = (open ?? openRecognizer)(model, modelPath(directory, model), vadPath(directory));
     try {
         return {
@@ -73,6 +124,14 @@ export const hearLocally = async (bytes, messageId, { model, directory, open, ff
         recognizer.free();
     }
 };
+/** Where a kept transcript came from, as `Kept` stores it: the messenger's provider, a local model, or `openai:<model>`. */
+export const keptSource = (heard) => heard.via === "openai" ? `openai:${heard.model ?? OPENAI_TRANSCRIBE_MODEL}` : (heard.model ?? heard.via);
+/** The reverse of `keptSource`. */
+export const heardVia = (source, provider) => source === provider
+    ? { via: source }
+    : source.startsWith("openai:")
+        ? { via: "openai", model: source.slice("openai:".length) }
+        : { via: "local", model: source };
 const readAll = async (file) => {
     const chunks = [];
     let total = 0;

package/dist/speech/wav.d.ts

@@ -25,3 +25,5 @@ export declare const openWavAudio: (plan: WavAudioPlan, input: WavAudioOptions)
     windows(): AsyncIterable<WavPcmWindow>;
     close(): Promise<void>;
 }>;
+/** PCM16 mono WAV of samples in [-1, 1], for a recognizer that takes a file. */
+export declare const encodeWav: (samples: Float32Array, sampleRate?: number) => Uint8Array;

package/dist/speech/wav.js

@@ -196,3 +196,23 @@ export const openWavAudio = async (plan, input) => {
         throw error;
     }
 };
+/** PCM16 mono WAV of samples in [-1, 1], for a recognizer that takes a file. */
+export const encodeWav = (samples, sampleRate = 16000) => {
+    const bytes = Buffer.alloc(44 + samples.length * 2);
+    bytes.write("RIFF", 0, "ascii");
+    bytes.writeUInt32LE(bytes.length - 8, 4);
+    bytes.write("WAVEfmt ", 8, "ascii");
+    bytes.writeUInt32LE(16, 16);
+    bytes.writeUInt16LE(1, 20);
+    bytes.writeUInt16LE(1, 22);
+    bytes.writeUInt32LE(sampleRate, 24);
+    bytes.writeUInt32LE(sampleRate * 2, 28);
+    bytes.writeUInt16LE(2, 32);
+    bytes.writeUInt16LE(16, 34);
+    bytes.write("data", 36, "ascii");
+    bytes.writeUInt32LE(samples.length * 2, 40);
+    samples.forEach((sample, index) => {
+        bytes.writeInt16LE(Math.round(Math.max(-1, Math.min(1, sample || 0)) * 32767), 44 + index * 2);
+    });
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.length);
+};

package/dist/store/index.d.ts

@@ -31,6 +31,7 @@ export { CATALOG_QUERY } from "./sqlite/catalog.js";
 export type { ChatMetadata } from "./sqlite/chats.js";
 export type { Email, EmailAddress, EmailAttachment, EmailFacts, EmailFilter, EmailInput, EmailInThread, EmailLocationInput, EmailRecipient, EmailRef, EmailThread, EmailVectorHit, FolderEmail, Mailbox, MailboxInput, MailFilter, MailStore, SenderScore, ThreadDetails, ThreadSave, } from "./sqlite/emails.js";
 export { EVENT_FIELDS, type EventChunkToEmbed, type EventHit, type EventQuery, type EventSearch, type NearestEvent, } from "./sqlite/event-search.js";
+export type { EvidenceSource } from "./sqlite/evidence-sources.js";
 export type { Fact, FactInput, FactsStore } from "./sqlite/facts.js";
 export type { FileListQuery, FilesStore, StoredFile } from "./sqlite/files.js";
 export { IMPORTED_DOCUMENT_QUERY, type ImportedDocuments } from "./sqlite/imported-documents.js";

package/dist/store/project-transfer/request.d.ts

@@ -6,7 +6,7 @@ export declare const projectAnnotationRequest: (request: ProjectAnnotationTarget
             ref: string;
             type: "decision" | "fact" | "promise" | "question" | "statement";
             statement: string;
-            status: "accepted" | "proposed" | "reversed" | "superseded";
+            status: "accepted" | "proposed" | "rejected" | "reversed" | "superseded";
             subject: string | null;
             occurred_at: number | null;
             supersedes: string | null;

package/dist/store/project-transfer/schema.d.ts

@@ -25,7 +25,7 @@ export declare const projectAnnotationsSchema: v.StrictObjectSchema<{
         readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
         readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
         readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
-        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed"], undefined>;
+        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed", "rejected"], undefined>;
         readonly subject: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
         readonly occurred_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
         readonly supersedes: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
@@ -40,7 +40,7 @@ export declare const projectAnnotationsSchema: v.StrictObjectSchema<{
         ref: string;
         type: "decision" | "fact" | "promise" | "question" | "statement";
         statement: string;
-        status: "accepted" | "proposed" | "reversed" | "superseded";
+        status: "accepted" | "proposed" | "rejected" | "reversed" | "superseded";
         subject: string | null;
         occurred_at: number | null;
         supersedes: string | null;

package/dist/store/project-transfer/snapshot-model.d.ts

@@ -6,7 +6,7 @@ export declare const projectAnnotationSnapshotSchema: v.StrictObjectSchema<{
         readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
         readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
         readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
-        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed"], undefined>;
+        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed", "rejected"], undefined>;
         readonly subject: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
         readonly occurred_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
         readonly supersedes: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
@@ -21,7 +21,7 @@ export declare const projectAnnotationSnapshotSchema: v.StrictObjectSchema<{
         ref: string;
         type: "decision" | "fact" | "promise" | "question" | "statement";
         statement: string;
-        status: "accepted" | "proposed" | "reversed" | "superseded";
+        status: "accepted" | "proposed" | "rejected" | "reversed" | "superseded";
         subject: string | null;
         occurred_at: number | null;
         supersedes: string | null;

package/dist/store/sqlite/evidence-sources.d.ts

@@ -0,0 +1,23 @@
+import type { CacheDatabase } from "../driver.js";
+/** One reference a memory or fact rests on, read back whole enough to judge it without opening it. */
+export interface EvidenceSource {
+    /** `null` when the row is gone from the store and its reference with it. */
+    ref: string | null;
+    kind: string;
+    title: string | null;
+    sender: string | null;
+    at: string | null;
+    excerpt: string | null;
+    /** The provider the source came through: `telegram`, `email`, `notes`, `zoom`… */
+    tool: string | null;
+    /** Deleted at its source since it was cited, or no longer in the store. */
+    missing: boolean;
+}
+/**
+ * Every `evidence` link from a memory or fact, in the order they were written, including one whose target was
+ * deleted since: `evidenceOf` drops those, so a reader would never learn the record lost a source.
+ */
+export declare const evidenceSourcesOf: (database: CacheDatabase, from: {
+    type: string;
+    id: number;
+}) => EvidenceSource[];

package/dist/store/sqlite/evidence-sources.js

@@ -0,0 +1,59 @@
+import { linkKind } from "./link-kinds.js";
+import { referenceOfThing, stateOfThing, storedThing } from "./things.js";
+const EXCERPT_CHARS = 280;
+const excerptOf = (text) => {
+    if (text == null)
+        return null;
+    const flat = String(text).replace(/\s+/g, " ").trim();
+    if (!flat)
+        return null;
+    return flat.length > EXCERPT_CHARS ? `${flat.slice(0, EXCERPT_CHARS - 1)}…` : flat;
+};
+const iso = (value) => (value == null ? null : new Date(Number(value)).toISOString());
+const textOf = (value) => (value == null || String(value).trim() === "" ? null : String(value));
+const READS = {
+    message: "SELECT c.title, coalesce(m.sender_name, i.name) AS sender, m.sent_at AS at, m.text AS body, a.provider AS tool " +
+        "FROM messages m JOIN chats c ON c.id = m.chat_id JOIN accounts a ON a.id = c.account_id " +
+        "LEFT JOIN identities i ON i.id = m.sender_identity_id WHERE m.id = ?",
+    email: "SELECT e.subject AS title, coalesce(e.from_name, e.from_address) AS sender, e.sent_at AS at, " +
+        "coalesce(e.body_text, e.snippet) AS body, 'email' AS tool FROM emails e WHERE e.id = ?",
+    note: "SELECT title, NULL AS sender, updated_at AS at, body, 'notes' AS tool FROM notes WHERE id = ?",
+    document: "SELECT d.title, NULL AS sender, coalesce(d.external_updated_at, d.updated_at) AS at, d.body, a.provider AS tool " +
+        "FROM documents d JOIN accounts a ON a.id = d.account_id WHERE d.id = ?",
+    meeting: "SELECT m.title, NULL AS sender, m.started_at AS at, m.description AS body, a.provider AS tool " +
+        "FROM meetings m JOIN accounts a ON a.id = m.account_id WHERE m.id = ?",
+    meeting_transcript: "SELECT m.title, NULL AS sender, m.started_at AS at, NULL AS body, a.provider AS tool FROM meeting_transcripts t " +
+        "JOIN meetings m ON m.id = t.meeting_id JOIN accounts a ON a.id = m.account_id WHERE t.id = ?",
+    meeting_transcript_row: "SELECT m.title, r.speaker_name AS sender, m.started_at + coalesce(r.start_ms, 0) AS at, r.text AS body, " +
+        "a.provider AS tool FROM meeting_transcript_rows r JOIN meeting_transcripts t ON t.id = r.meeting_transcript_id " +
+        "JOIN meetings m ON m.id = t.meeting_id JOIN accounts a ON a.id = m.account_id WHERE r.id = ?",
+};
+const KIND = {
+    meeting_transcript: "meeting",
+    meeting_transcript_row: "meeting",
+};
+/**
+ * Every `evidence` link from a memory or fact, in the order they were written, including one whose target was
+ * deleted since: `evidenceOf` drops those, so a reader would never learn the record lost a source.
+ */
+export const evidenceSourcesOf = (database, from) => database
+    .prepare(`SELECT to_type, to_id FROM links WHERE from_type = ? AND from_id = ? AND kind = ${linkKind("evidence")} ` +
+    "AND to_id IS NOT NULL ORDER BY id")
+    .all(from.type, from.id)
+    .map((link) => {
+    const thing = storedThing(link.to_type, link.to_id);
+    const state = stateOfThing(database, thing);
+    const read = READS[thing.type];
+    const row = read === undefined || state === "unavailable" ? undefined : database.prepare(read).get(thing.id);
+    const gone = state !== "available";
+    return {
+        ref: referenceOfThing(database, thing) ?? null,
+        kind: KIND[thing.type] ?? thing.type,
+        title: textOf(row?.title),
+        sender: textOf(row?.sender),
+        at: iso(row?.at),
+        excerpt: gone ? null : excerptOf(row?.body),
+        tool: textOf(row?.tool),
+        missing: gone,
+    };
+});

package/dist/store/sqlite/facts.d.ts

@@ -1,5 +1,6 @@
 import { type FACT_STATUSES, FACT_TYPES, MEMORY_SCOPES } from "../../domain/knowledge.js";
 import type { Actor } from "./actors.js";
+import { type EvidenceSource } from "./evidence-sources.js";
 import { type Author } from "./memories.js";
 import type { StoreContext } from "./open.js";
 /** What happened, as its evidence shows; its evidence is `links` of kind `evidence`. */
@@ -12,6 +13,8 @@ export interface Fact {
     status: (typeof FACT_STATUSES)[number];
     project: string | null;
     subject: string | null;
+    subjectName: string | null;
+    subjectIsOwner: boolean;
     occurredAt: string | null;
     supersedes: string | null;
     /** `name` is a bot's handle; `null` for a person. */
@@ -61,6 +64,19 @@ export interface FactsStore {
     accept(reference: string): Promise<Fact>;
     /** An accepted decision no longer holds and nothing replaced it. */
     reverse(reference: string): Promise<Fact>;
+    /** The owner turns down a proposed fact; it stays, marked `rejected`. */
+    reject(reference: string): Promise<Fact>;
+    /**
+     * Erases the fact: its row, its links, its tags, and the memory it was migrated from, which still held its text.
+     * A decision that replaced it no longer names it. A backup made before keeps it.
+     */
+    remove(reference: string): Promise<{
+        ref: string;
+        removed: true;
+        links: number;
+    }>;
+    /** Each reference it rests on, read back; one deleted since is `missing`. */
+    sources(reference: string): Promise<EvidenceSource[]>;
 }
 type FactOperations = {
     [K in keyof FactsStore]: FactsStore[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => R : never;

package/dist/store/sqlite/facts.js

@@ -1,10 +1,10 @@
 import { CliError } from "@wirecat/cli-base";
 import { FACT_TYPES, MEMORY_SCOPES } from "../../domain/knowledge.js";
 import { calendarMoment } from "../../domain/moment.js";
+import { evidenceSourcesOf } from "./evidence-sources.js";
 import { linkKind } from "./link-kinds.js";
-import { authorActor, authorOf, evidenceOf, linkEvidence } from "./memories.js";
+import { authorActor, authorOf, dropLinksOf, erase, evidenceOf, linkEvidence, subjectOf, } from "./memories.js";
 import { requiredThing } from "./notes.js";
-import { referenceOfThing, storedThing } from "./things.js";
 import { write } from "./transaction.js";
 const NAMED = "SELECT f.*, b.name AS author_name FROM facts f LEFT JOIN bots b ON f.author_type = 'bot' AND b.id = f.author_id";
 const iso = (value) => new Date(Number(value)).toISOString();
@@ -22,9 +22,7 @@ export const factOperationsOver = (context) => {
         statement: String(row.statement),
         status: row.status,
         project: row.project_id == null ? null : `project:${row.project_id}`,
-        subject: row.subject_type == null
-            ? null
-            : (referenceOfThing(database, storedThing(row.subject_type, row.subject_id)) ?? null),
+        ...subjectOf(database, row),
         occurredAt: row.occurred_at == null ? null : iso(row.occurred_at),
         supersedes: row.supersedes_id == null ? null : `fact:${row.supersedes_id}`,
         author: authorOf(row),
@@ -125,8 +123,41 @@ export const factOperationsOver = (context) => {
             database.prepare("UPDATE facts SET status = 'reversed', updated_at = ? WHERE id = ?").run(now(), Number(row.id));
             return factOf(rowOf(reference));
         },
+        reject: (reference) => {
+            const row = rowOf(reference);
+            if (row.status !== "proposed")
+                throw new CliError("validation_error", `only a proposed fact can be rejected; this one is ${String(row.status)}`);
+            database.prepare("UPDATE facts SET status = 'rejected', updated_at = ? WHERE id = ?").run(now(), Number(row.id));
+            return factOf(rowOf(reference));
+        },
+        remove: (reference) => {
+            const row = rowOf(reference);
+            const id = Number(row.id);
+            const twin = row.source === "memory" && row.metadata != null ? migratedFrom(String(row.metadata)) : undefined;
+            const links = erase(database, () => {
+                database.prepare("UPDATE facts SET supersedes_id = NULL WHERE supersedes_id = ?").run(id);
+                const count = dropLinksOf(database, { type: "fact", id });
+                database.prepare("DELETE FROM links WHERE from_type = 'fact' AND from_id = ?").run(id);
+                database.prepare("DELETE FROM taggings WHERE taggable_type = 'fact' AND taggable_id = ?").run(id);
+                database.prepare("DELETE FROM facts WHERE id = ?").run(id);
+                if (twin !== undefined)
+                    database.prepare("DELETE FROM memories WHERE id = ? AND deleted_at IS NOT NULL").run(twin);
+                return count;
+            });
+            return { ref: `fact:${id}`, removed: true, links };
+        },
+        sources: (reference) => evidenceSourcesOf(database, { type: "fact", id: Number(rowOf(reference).id) }),
     };
 };
+const migratedFrom = (metadata) => {
+    try {
+        const { memory } = JSON.parse(metadata);
+        return Number.isInteger(memory) ? Number(memory) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 export const factsStoreOver = (context) => {
     const operations = factOperationsOver(context);
     return {
@@ -135,5 +166,8 @@ export const factsStoreOver = (context) => {
         list: async (options) => operations.list(options),
         accept: async (reference) => operations.accept(reference),
         reverse: async (reference) => operations.reverse(reference),
+        reject: async (reference) => operations.reject(reference),
+        remove: async (reference) => operations.remove(reference),
+        sources: async (reference) => operations.sources(reference),
     };
 };

package/dist/store/sqlite/memories.d.ts

@@ -1,5 +1,6 @@
 import { MEMORY_KINDS, MEMORY_SCOPES, type MEMORY_STATUSES } from "../../domain/knowledge.js";
 import { type Actor } from "./actors.js";
+import { type EvidenceSource } from "./evidence-sources.js";
 import { type NoteIndexState } from "./note-index.js";
 import type { StoreContext } from "./open.js";
 /** Who wrote it: the owner, or an agent by its bot handle and the model it ran on. */
@@ -14,6 +15,10 @@ export interface Memory {
     body: string;
     /** What it is about, as a reference; `null` for a general fact. */
     subject: string | null;
+    /** What the subject is called; `null` for the owner, who has no name in the store, and for a nameless row. */
+    subjectName: string | null;
+    /** The subject is the owner. */
+    subjectIsOwner: boolean;
     /** `name` is a bot's handle; `null` for a person. */
     author: {
         type: Actor["type"];
@@ -59,6 +64,17 @@ export interface MemoriesStore {
     confirm(reference: string): Promise<Memory>;
     /** Its evidence no longer holds. */
     markStale(reference: string): Promise<Memory>;
+    /**
+     * Erases the memory: its row, its text in the search and meaning indexes, and every link from or to it. A memory
+     * that replaced it no longer names it. A backup made before keeps it.
+     */
+    remove(reference: string): Promise<{
+        ref: string;
+        removed: true;
+        links: number;
+    }>;
+    /** Each reference it rests on, read back; one deleted since is `missing`. */
+    sources(reference: string): Promise<EvidenceSource[]>;
     /** Indexes what was written since, then finds memories holding every word or a longer one it starts, best first. */
     search(text: string, options?: {
         subject?: string;
@@ -82,5 +98,17 @@ export declare const evidenceOf: (context: StoreContext, from: {
     type: string;
     id: number;
 }) => string[];
+/** What a memory's or fact's subject is called, for a reader who should not have to look the reference up. */
+export declare const subjectOf: (database: StoreContext["database"], row: Row) => Pick<Memory, "subject" | "subjectName" | "subjectIsOwner">;
+/** Counts every link from or to a row and drops the ones its delete trigger does not: those pointing at it. */
+export declare const dropLinksOf: (database: StoreContext["database"], thing: {
+    type: string;
+    id: number;
+}) => number;
+/**
+ * Runs a delete so the text does not linger in the file: freed pages are zeroed, the words indexes merged so no
+ * segment still holds the erased words, and the write-ahead log emptied when no reader holds it.
+ */
+export declare const erase: <T>(database: StoreContext["database"], work: () => T) => T;
 export declare const memoriesStoreOver: (context: StoreContext) => MemoriesStore;
 export {};