@wirecat/cli-core 0.499.0 → 0.501.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ shape of this file.
 
 ## Unreleased
 
+## 0.501.0 — 31.10.2026
+
+### Added
+
+- **Search answers say how many match in all: `page.total`.** `search notes` and `search messages` add
+  `page.total: { value, relation }` to `--json`, and `NotesFound.total` / `SearchFound.total` carry it to a tool that
+  builds its own answer (drive prints it as `item.total`; memo's notes, messages and mail pass it on with their next
+  release). It is shaped as Elasticsearch's `hits.total`: `relation` is `eq` for an exact count and `gte` for a lower bound. The terminal adds a line such as
+  `showing 1–20 of 144` (`144+` for a lower bound). Notes count every note the words find plus every note found by
+  meaning; messages count the strict query's matches, or discovery's candidates with `--discover`. Counting stops at
+  10,000 (`TOTAL_CAP`, Elasticsearch's default), and a query whose leaves are checked row by row (a preset, a
+  pattern) gets the lower bound the page proves. New: `SearchTotal`, `NotesFound.total`, `SearchFound.total`,
+  `NoteSearch.matchingRefs` (refs only, no note read), `NoteSearch.scoreNotes` and `QueriesStore.countMatches`;
+  `listOf` takes `total`, and `shownOf(shown, offset, total)` from `@wirecat/cli-core/cli` writes the terminal line.
+
+### Changed — may break callers
+
+- **cli-core needs `@wirecat/cli-base` 0.67.** The peer range moves from `>=0.65.0 <0.66.0` to `>=0.67.0 <0.68.0`. A
+  CLI that pins cli-base moves its pin with this release. cli-base 0.67 adds `page.total` to the list envelope.
+
+### Fixed
+
+- **Search by meaning inside a filter ranks the filter's own notes.** With a filter that holds at most 2,000 notes
+  (`RANK_WITHIN`), `search notes` scores every one of them by meaning, instead of taking the 50 nearest notes overall
+  and dropping those outside the filter. On the owner's store, Drive's `budget date>=30d` went from 7 hits to a full
+  page of 20, and 50 of the 144 documents in the date range match in all; no hit falls outside the filter, as
+  before. A larger filter keeps the old way, as does one the store cannot list cheaply.
+
+## 0.500.0 — 31.10.2026
+
+### Added
+
+- **A memory or fact can be forgotten for good.** `store.memories.remove(ref)` and `store.facts.remove(ref)` erase the
+  row, every link from or to it, its tags, and its words, pieces and vectors in the search indexes, in one write. The
+  words indexes are merged and freed pages zeroed (`secure_delete`), so the text is not left in the file; the
+  write-ahead log is emptied when no reader holds it. A record that replaced it no longer names it (`supersedes:
+  null`). Removing a fact also erases the soft-deleted memory it was migrated from in version 2, which still held its
+  text. Both answer `{ ref, removed: true, links }`, where `links` counts the links erased.
+- **`store.facts.reject(ref)`** turns down a proposed fact: `FACT_STATUSES` gains `rejected`.
+- **`store.memories.sources(ref)` and `store.facts.sources(ref)`** read each evidence link back as an `EvidenceSource`:
+  `ref`, `kind`, `title`, `sender`, `at`, `excerpt` (280 characters at most), `tool` and `missing`. A source deleted
+  since is still listed, `missing: true` with no excerpt, where `evidence` leaves it out; `ref` is `null` when its row
+  is gone from the store.
+- **`Memory` and `Fact` carry `subjectName` and `subjectIsOwner`.** A person is named by their name, else the
+  owner's alias for them, else an identity's name; a project or organization by its name. The owner has no name in the
+  store, so `subjectName` is `null` and `subjectIsOwner` is `true`. The `memory` and `fact` entities gain optional
+  `subject_name`, `subject_is_owner` and `sources`.
+
 ## 0.499.0 — 31.10.2026
 
 ### Added

package/dist/calendar/mcp/index.d.ts

@@ -10,13 +10,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
@@ -38,9 +38,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -50,9 +50,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -71,13 +71,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
@@ -99,9 +99,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -111,9 +111,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -132,13 +132,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
@@ -160,9 +160,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -172,9 +172,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };
@@ -193,13 +193,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
         } | {
             account_id: {
@@ -221,9 +221,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event: {
                 type: string;
                 minLength: number;
@@ -233,9 +233,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             words?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             event?: undefined;
             account_id?: undefined;
         };

package/dist/cli/envelope.d.ts

@@ -1,5 +1,5 @@
 import { type Renderer, type RenderFormat, type Streams } from "@wirecat/cli-base";
-import { type ItemEnvelope, type ListEnvelope, type Meta, type Missing, type NextStep, type StepInput } from "@wirecat/cli-base/standards";
+import { type ItemEnvelope, type ListEnvelope, type Meta, type Missing, type NextStep, type StepInput, type Total } from "@wirecat/cli-base/standards";
 import type { Command } from "commander";
 import * as v from "valibot";
 export type ListBody<T> = Omit<ListEnvelope<T>, "meta"> & {
@@ -19,6 +19,8 @@ export interface ListInput<T> {
     paging?: "cursor";
     /** The page shown, from 1, for a list paged by `--page`. */
     page?: number;
+    /** How many match, every page together, for a search that counts them. */
+    total?: Total;
     /** The command's own arguments and query, so `page.next` reruns the same list. */
     args?: Record<string, unknown>;
     next?: NextStep[];
@@ -33,11 +35,19 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 2, undefined>]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>, v.StrictObjectSchema<{
         readonly mode: v.LiteralSchema<"cursor", undefined>;
         readonly limit: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>;
         readonly has_more: v.BooleanSchema<undefined>;
         readonly next_cursor: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly total: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly value: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly relation: v.PicklistSchema<["eq", "gte"], undefined>;
+        }, undefined>, undefined>;
     }, undefined>], undefined>;
     readonly next: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.VariantSchema<"kind", [v.StrictObjectSchema<{
         readonly kind: v.LiteralSchema<"command", undefined>;

package/dist/cli/envelope.js

@@ -14,7 +14,7 @@ const capped = (steps) => (steps.length > 0 ? { next: steps.slice(0, MAX_NEXT_ST
  * page where the source has no cursor.
  */
 export const listOf = (command, input) => {
-    const { items, limit, has_more, cursor, paging, page, args = {}, next = [], missing, meta } = input;
+    const { items, limit, has_more, cursor, paging, page, total, args = {}, next = [], missing, meta } = input;
     const byCursor = paging === "cursor" || cursor !== undefined;
     const more = has_more
         ? [
@@ -28,8 +28,20 @@ export const listOf = (command, input) => {
     const body = {
         items,
         page: byCursor
-            ? { mode: "cursor", limit, has_more, ...(has_more && cursor !== undefined ? { next_cursor: cursor } : {}) }
-            : { mode: "page", limit, has_more, ...(has_more ? { next_page: (page ?? 1) + 1 } : {}) },
+            ? {
+                mode: "cursor",
+                limit,
+                has_more,
+                ...(has_more && cursor !== undefined ? { next_cursor: cursor } : {}),
+                ...(total ? { total } : {}),
+            }
+            : {
+                mode: "page",
+                limit,
+                has_more,
+                ...(has_more ? { next_page: (page ?? 1) + 1 } : {}),
+                ...(total ? { total } : {}),
+            },
         ...capped([...more, ...next]),
         ...(missing && missing.length > 0 ? { missing } : {}),
         ...(meta ? { meta } : {}),

package/dist/cli/index.d.ts

@@ -96,7 +96,7 @@ export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from ".
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, type MemberFetches, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/index.js

@@ -87,7 +87,7 @@ export { httpTokenFile, serverEntry } from "./messenger/mcp-command.js";
 export { messageItem } from "./messenger/message-items.js";
 export { privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, coverageGaps, messageHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, messageHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/meeting-preparation-answer.d.ts

@@ -345,11 +345,19 @@ export declare const meetingPreparationAnswer: (packet: MeetingPreparation) => i
                 limit: number;
                 has_more: boolean;
                 next_page?: number | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             } | {
                 mode: "cursor";
                 limit: number;
                 has_more: boolean;
                 next_cursor?: string | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             };
             coverage: {
                 archive_completeness: "unknown";

package/dist/cli/meeting-preparation-projects.d.ts

@@ -65,11 +65,19 @@ export declare const mapPreparationProjectEvidence: (section: NonNullable<Meetin
             limit: number;
             has_more: boolean;
             next_page?: number | undefined;
+            total?: {
+                value: number;
+                relation: "eq" | "gte";
+            } | undefined;
         } | {
             mode: "cursor";
             limit: number;
             has_more: boolean;
             next_cursor?: string | undefined;
+            total?: {
+                value: number;
+                relation: "eq" | "gte";
+            } | undefined;
         };
         coverage: {
             archive_completeness: "unknown";

package/dist/cli/meeting-preparation-read.d.ts

@@ -374,11 +374,19 @@ export declare const readMeetingPreparation: (read: MeetingPreparationReader, in
                 limit: number;
                 has_more: boolean;
                 next_page?: number | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             } | {
                 mode: "cursor";
                 limit: number;
                 has_more: boolean;
                 next_cursor?: string | undefined;
+                total?: {
+                    value: number;
+                    relation: "eq" | "gte";
+                } | undefined;
             };
             coverage: {
                 archive_completeness: "unknown";

package/dist/cli/meeting-series-inventory-read.d.ts

@@ -34,11 +34,19 @@ export declare const readMeetingSeriesInventory: (read: MeetingSeriesInventoryRe
         limit: number;
         has_more: boolean;
         next_page?: number | undefined;
+        total?: {
+            value: number;
+            relation: "eq" | "gte";
+        } | undefined;
     } | {
         mode: "cursor";
         limit: number;
         has_more: boolean;
         next_cursor?: string | undefined;
+        total?: {
+            value: number;
+            relation: "eq" | "gte";
+        } | undefined;
     };
     fingerprint: string;
     limits: {

package/dist/cli/messenger/messages-search-command.js

@@ -12,7 +12,7 @@ import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { archiveSummary } from "./archive-summary.js";
 import { messengerContext } from "./context.js";
-import { meaningNote, messagesAnswer, offsetOf } from "./search-answers.js";
+import { meaningNote, messagesAnswer, offsetOf, shownOf } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { syncOptions, syncRequest, syncsFirst } from "./search-sync-options.js";
 import { threadOptions, threadRequest } from "./thread-options.js";
@@ -184,6 +184,9 @@ const searchAction = (messenger) => async function (given) {
         if (elsewhere.length > 0) {
             context.renderer.note(`hits in ${elsewhere.join(", ")} open in that messenger's own CLI, by the locator: messages context msg:…`);
         }
+        const shown = shownOf(found.items.length, offsetOf(page, limit) ?? 0, found.total);
+        if (shown)
+            context.renderer.note(shown);
         if (found.items.length === 0)
             context.renderer.note(found.server && !found.server.skipped
                 ? "nothing found in the local store or on the messenger's server"

package/dist/cli/messenger/search-answers.d.ts

@@ -1,6 +1,7 @@
 import type { Missing, NextStep } from "@wirecat/cli-base/standards";
 import type { InferOutput } from "valibot";
 import type { ENTITIES } from "../../entities/index.js";
+import type { SearchTotal } from "../../search/total.js";
 import type { ChatCoverage } from "../../services/chat-coverage.js";
 import type { FoundMessage, SearchFound } from "../../services/messages.js";
 import type { MeaningSkipped } from "../../services/messages-discovery.js";
@@ -33,6 +34,8 @@ export interface Paging {
     /** The query and options `page.next` repeats. */
     again?: Record<string, unknown>;
 }
+/** "showing 20 of 144", for the human view under a page of hits; `+` when the total is a lower bound. */
+export declare const shownOf: (shown: number, offset: number, total: SearchTotal | undefined) => string | undefined;
 /** `search messages` and `search mail`, CLI and MCP alike. */
 export declare const messagesAnswer: (command: string, found: SearchFound, { limit, page, again }: Paging, query?: string) => ListBody<MessageHitItem>;
 export declare const noteHitItem: (hit: FoundNote) => NoteHitItem;

package/dist/cli/messenger/search-answers.js

@@ -227,6 +227,10 @@ const pictureItems = (found) => {
         untrusted: ["sender_name"],
     }));
 };
+/** "showing 20 of 144", for the human view under a page of hits; `+` when the total is a lower bound. */
+export const shownOf = (shown, offset, total) => total === undefined || shown === 0
+    ? undefined
+    : `showing ${offset + 1}–${offset + shown} of ${total.value}${total.relation === "gte" ? "+" : ""}`;
 /** `search messages` and `search mail`, CLI and MCP alike. */
 export const messagesAnswer = (command, found, { limit, page, again }, query = "") => {
     const accounts = found.coverage?.accounts ?? found.accounts ?? [];
@@ -235,6 +239,7 @@ export const messagesAnswer = (command, found, { limit, page, again }, query = "
         limit,
         has_more: found.hasMore && (page ?? 1) * limit <= MAX_SEARCH_OFFSET,
         page: page ?? 1,
+        ...(found.total ? { total: found.total } : {}),
         ...(again ? { args: again } : {}),
         ...gapsOf(found),
         meta: metaOf(accounts, found.skipped, coverageGaps(found).missing.length > 0),
@@ -297,6 +302,7 @@ export const notesAnswer = (command, found, { limit, page, again }, exact = fals
     limit,
     has_more: found.has_more && found.next_offset !== undefined,
     page: page ?? 1,
+    total: found.total,
     ...(again ? { args: again } : {}),
     ...meaningGap(found.meaning_skipped, exact),
     meta: metaOf(found.accounts, found.skipped),

package/dist/cli/messenger/search-command.js

@@ -11,7 +11,7 @@ import { commandAt } from "../steps.js";
 import { messengerContext } from "./context.js";
 import { conversationsSearchCommand } from "./conversations-command.js";
 import { messagesSearchCommand } from "./messages-search-command.js";
-import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, } from "./search-answers.js";
+import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, shownOf, } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { topicsSearchCommand } from "./topics-command.js";
 const onlyOf = (value) => {
@@ -150,6 +150,9 @@ const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LO
     renderAnswer(this, context, notesAnswer("search notes", found, { limit, page: options.page ?? 1, again }), () => {
         if (found.hits.length === 0)
             context.renderer.note("no note matches");
+        const shown = shownOf(found.hits.length, ((options.page ?? 1) - 1) * limit, found.total);
+        if (shown)
+            context.renderer.note(shown);
         return found.hits
             .map((hit) => `${singleLine(hit.title ?? hit.path ?? hit.ref)}  ${hit.ref}  (${hit.found_by.join(", ")})${hit.url ? `\n  ${singleLine(hit.url)}` : ""}\n  ${singleLine(hit.excerpt)}\n`)
             .join("");

package/dist/domain/knowledge.d.ts

@@ -1,5 +1,5 @@
 export declare const FACT_TYPES: readonly ["fact", "statement", "question", "decision", "promise"];
-export declare const FACT_STATUSES: readonly ["proposed", "accepted", "superseded", "reversed"];
+export declare const FACT_STATUSES: readonly ["proposed", "accepted", "superseded", "reversed", "rejected"];
 export declare const MEMORY_KINDS: readonly ["summary", "digest", "preference"];
 export declare const MEMORY_STATUSES: readonly ["proposed", "confirmed", "stale", "superseded"];
 export declare const MEMORY_SCOPES: readonly ["personal", "work"];

package/dist/domain/knowledge.js

@@ -1,6 +1,6 @@
 import { TASK_KINDS } from "../tasks/index.js";
 export const FACT_TYPES = ["fact", "statement", "question", "decision", "promise"];
-export const FACT_STATUSES = ["proposed", "accepted", "superseded", "reversed"];
+export const FACT_STATUSES = ["proposed", "accepted", "superseded", "reversed", "rejected"];
 export const MEMORY_KINDS = ["summary", "digest", "preference"];
 export const MEMORY_STATUSES = ["proposed", "confirmed", "stale", "superseded"];
 export const MEMORY_SCOPES = ["personal", "work"];

package/dist/entities/fact.d.ts

@@ -4,9 +4,12 @@ export declare const fact: v.StrictObjectSchema<{
     readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
     readonly kind: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
     readonly text: v.StringSchema<undefined>;
-    readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed"], undefined>;
+    readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed", "rejected"], undefined>;
     readonly project: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly subject: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    /** What the subject is called; `null` for the owner and for a row with no name. */
+    readonly subject_name: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly subject_is_owner: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
     readonly occurred_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     readonly supersedes: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
     readonly author: v.StrictObjectSchema<{
@@ -24,6 +27,17 @@ export declare const fact: v.StrictObjectSchema<{
     /** Who recorded it: the owner, or an agent whose fact waits as proposed. */
     readonly origin: v.PicklistSchema<["owner", "agent"], undefined>;
     readonly evidence: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    /** With `--sources`: each piece of evidence read back. */
+    readonly sources: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly sender: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly excerpt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly tool: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly missing: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>, undefined>;
     readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
     readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
 }, undefined>;

package/dist/entities/fact.js

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { FACT_STATUSES, FACT_TYPES, MEMORY_SCOPES } from "../domain/knowledge.js";
-import { author, id, reference, text, time } from "./fields.js";
+import { author, evidenceSource, id, reference, text, time } from "./fields.js";
 export const fact = v.strictObject({
     ref: reference,
     id,
@@ -9,6 +9,9 @@ export const fact = v.strictObject({
     status: v.picklist(FACT_STATUSES),
     project: v.nullable(text),
     subject: v.nullable(reference),
+    /** What the subject is called; `null` for the owner and for a row with no name. */
+    subject_name: v.optional(v.nullable(text)),
+    subject_is_owner: v.optional(v.boolean()),
     occurred_at: v.nullable(time),
     supersedes: v.nullable(reference),
     author,
@@ -19,6 +22,8 @@ export const fact = v.strictObject({
     /** Who recorded it: the owner, or an agent whose fact waits as proposed. */
     origin: v.picklist(["owner", "agent"]),
     evidence: v.array(reference),
+    /** With `--sources`: each piece of evidence read back. */
+    sources: v.optional(v.array(evidenceSource)),
     created_at: time,
     updated_at: time,
 });

package/dist/entities/fields.d.ts

@@ -10,6 +10,17 @@ export declare const count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>
 /** Fields of an answer item someone other than the owner wrote, as dotted paths: an agent reads them as data. */
 export declare const untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
 export declare const providerMetadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+/** A reference a memory or fact rests on, read back; `missing` once it was deleted since. */
+export declare const evidenceSource: v.StrictObjectSchema<{
+    readonly ref: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly kind: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly sender: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+    readonly excerpt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly tool: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly missing: v.BooleanSchema<undefined>;
+}, undefined>;
 export declare const author: v.StrictObjectSchema<{
     readonly type: v.PicklistSchema<["person", "bot"], undefined>;
     readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;

package/dist/entities/fields.js

@@ -10,6 +10,17 @@ export const count = v.pipe(v.number(), v.integer(), v.minValue(0));
 /** Fields of an answer item someone other than the owner wrote, as dotted paths: an agent reads them as data. */
 export const untrusted = v.optional(v.array(text));
 export const providerMetadata = v.optional(v.record(v.string(), v.unknown()));
+/** A reference a memory or fact rests on, read back; `missing` once it was deleted since. */
+export const evidenceSource = v.strictObject({
+    ref: v.nullable(reference),
+    kind: text,
+    title: v.nullable(text),
+    sender: v.nullable(text),
+    at: v.nullable(time),
+    excerpt: v.nullable(text),
+    tool: v.nullable(text),
+    missing: v.boolean(),
+});
 export const author = v.strictObject({
     type: v.picklist(["person", "bot"]),
     id,