@wirecat/cli-core 0.548.0 → 0.550.0

package/dist/output-detail.js

@@ -2,13 +2,17 @@ export const DETAILS = ["brief", "full"];
 /** Message fields mail never has and a messenger hit rarely fills; a null one is noise. */
 const RARELY_SET = ["editedAt", "replyTo", "forwardedFrom", "reactions"];
 const BRIEF = ["locator", "chatTitle", "timestamp", "senderName", "excerpt", "score"];
-const isHit = (value) => typeof value === "object" &&
-    value !== null &&
-    typeof value.locator === "string" &&
-    typeof value.text === "string";
+/** A messenger answer's hit (`message.hit`): already cut to an excerpt, so only `brief` changes it. */
+const SNAKE_BRIEF = ["ref", "chat_title", "timestamp", "sender_name", "excerpt", "score"];
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isSnakeHit = (value) => isRecord(value) && typeof value.ref === "string" && typeof value.excerpt === "string";
+const isHit = (value) => isSnakeHit(value) || (isRecord(value) && typeof value.locator === "string" && typeof value.text === "string");
+const picked = (hit, keys) => Object.fromEntries(keys.flatMap((key) => (hit[key] === undefined || hit[key] === null ? [] : [[key, hit[key]]])));
 const shaped = (hit, detail) => {
+    if (isSnakeHit(hit))
+        return detail === "brief" ? picked(hit, SNAKE_BRIEF) : hit;
     if (detail === "brief")
-        return Object.fromEntries(BRIEF.flatMap((key) => (hit[key] === undefined || hit[key] === null ? [] : [[key, hit[key]]])));
+        return picked(hit, BRIEF);
     const { text, providerMetadata, ...rest } = hit;
     for (const key of RARELY_SET)
         if (rest[key] === null)

package/dist/output.d.ts

@@ -14,6 +14,8 @@ export interface OutputOptions {
     hitDetail?: Detail;
     /** Takes the answer as an object in place of printing it — an agent's run (`BaseEnvironment.agent`). */
     capture?: (value: unknown) => void;
+    /** One line per item (WC-OUT-24); anything printed past `renderAnswer` stays JSON. */
+    compact?: boolean;
 }
 /**
  * One place decides the mode, so no command can disagree with another.
@@ -23,9 +25,11 @@ export interface OutputOptions {
  * instead. In every machine mode **stdout carries JSON and nothing else** — diagnostics are on stderr in all modes, which is what makes
  * that contract hold by construction rather than by remembering.
  */
-export declare const resolveOutput: ({ json, jsonl, quiet, streams, tty, color, fields, hitDetail, env, capture, }?: OutputOptions) => {
+export declare const resolveOutput: ({ json, jsonl, quiet, streams, tty, color, fields, hitDetail, env, capture, compact, }?: OutputOptions) => {
     format: "json" | "jsonl" | "pretty";
     color: boolean;
     streams: Streams;
     renderer: Renderer;
+    compact?: boolean | undefined;
+    full?: boolean | undefined;
 };

package/dist/output.js

@@ -1,6 +1,23 @@
-import { createRenderer, processStreams, singleLine, } from "@wirecat/cli-base";
+import { CliError, createRenderer, processStreams, singleLine, } from "@wirecat/cli-base";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
 import { fieldsOf, projectFields } from "./cli/result-fields.js";
 import { atDetail } from "./output-detail.js";
+const refuseCompact = ({ json, jsonl, fields, hitDetail }) => {
+    const other = jsonl
+        ? "--jsonl"
+        : fields !== undefined
+            ? "--json=…"
+            : json
+                ? "--json"
+                : hitDetail === "brief"
+                    ? "--brief"
+                    : "";
+    if (other)
+        throw new CliError("validation_error", `${COMPACT_FLAG} and ${other} ask for different output — pick one`, {
+            reason: "output.conflict",
+            param: COMPACT_FLAG,
+        });
+};
 /**
  * One place decides the mode, so no command can disagree with another.
  *
@@ -9,9 +26,11 @@ import { atDetail } from "./output-detail.js";
  * instead. In every machine mode **stdout carries JSON and nothing else** — diagnostics are on stderr in all modes, which is what makes
  * that contract hold by construction rather than by remembering.
  */
-export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tty, color, fields, hitDetail, env = process.env, capture, } = {}) => {
+export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tty, color, fields, hitDetail, env = process.env, capture, compact, } = {}) => {
+    if (compact)
+        refuseCompact({ json, jsonl, fields, hitDetail });
     const interactive = tty ?? process.stdout.isTTY === true;
-    const format = jsonl ? "jsonl" : json || !interactive ? "json" : "pretty";
+    const format = jsonl ? "jsonl" : json || compact || !interactive ? "json" : "pretty";
     const painted = format === "pretty" && (color ?? (env.NO_COLOR === undefined && env.TERM !== "dumb" && !env.CI));
     const printing = createRenderer({ format, color: painted, streams });
     const rendered = capture
@@ -37,7 +56,13 @@ export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tt
                 stream: (items) => created.stream([...items].map((item) => projectFields(item, paths))),
             }
             : created;
-    return { format, color: painted, streams, renderer: quiet ? silence(renderer) : renderer };
+    return {
+        format,
+        color: painted,
+        streams,
+        renderer: quiet ? silence(renderer) : renderer,
+        ...(compact ? { compact: true, full: hitDetail === "full" } : {}),
+    };
 };
 /** Fields a person writes in paragraphs; every other string is a name, a title, an id or a path. */
 const MULTI_LINE = new Set(["text", "description"]);

package/dist/services/proposals/kinds/relationship-update.d.ts

@@ -0,0 +1,4 @@
+import type { MessageStore } from "../../../store/index.js";
+import type { ProposalKind } from "../types.js";
+/** An agent's change to a relationship's role or purpose; the owner's applies at once and never waits here. */
+export declare const relationshipUpdateKind: (store: Pick<MessageStore, "knowledge" | "proposedActions">) => ProposalKind;

package/dist/services/proposals/kinds/relationship-update.js

@@ -0,0 +1,53 @@
+import { proposerOfAction } from "../../../store/index.js";
+import { actionStatus, kept, projectOf, pushed, storedStatus } from "./shared.js";
+const KIND = "relationship_update";
+const summaryOf = ({ changes }) => Object.entries(changes)
+    .map(([field, value]) => `${field} ${value ?? "cleared"}`)
+    .join(", ");
+const rowOf = (action) => {
+    const payload = action.payload;
+    return {
+        id: action.id,
+        kind: KIND,
+        status: actionStatus(action.status),
+        project: projectOf(payload.to, payload.from),
+        subject: `relationship:${payload.relationship}`,
+        object: payload.to,
+        summary: summaryOf(payload),
+        proposedBy: proposerOfAction(action),
+        reason: action.reason,
+        evidence: [],
+        score: null,
+        signals: null,
+        parts: null,
+        createdAt: action.createdAt,
+    };
+};
+/** An agent's change to a relationship's role or purpose; the owner's applies at once and never waits here. */
+export const relationshipUpdateKind = (store) => ({
+    kind: KIND,
+    stored: [KIND],
+    list: async (filter) => {
+        const status = storedStatus(filter);
+        const stored = await store.proposedActions.list({
+            kinds: [KIND],
+            ...(status === undefined ? {} : { status }),
+            ...pushed(filter),
+        });
+        return kept(stored.map(rowOf), filter);
+    },
+    get: async (id) => rowOf(await store.proposedActions.get(id)),
+    decide: async (id, { confirm, by, reason }) => {
+        const { relation } = await store.knowledge.decideRelationUpdate(id, {
+            confirm,
+            by,
+            ...(reason === undefined ? {} : { reason }),
+        });
+        return {
+            id,
+            kind: KIND,
+            status: confirm ? "confirmed" : "rejected",
+            made: relation ? [`relationship:${relation.id}`] : [],
+        };
+    },
+});

package/dist/services/proposals/registry.js

@@ -6,6 +6,7 @@ import { findingsKind } from "./kinds/findings.js";
 import { keyDocumentKind } from "./kinds/key-document.js";
 import { memoryKind } from "./kinds/memory.js";
 import { relationshipKind } from "./kinds/relationship.js";
+import { relationshipUpdateKind } from "./kinds/relationship-update.js";
 const PREFIX = /^([a-z][a-z_]*):/;
 const refusalOf = (id, error) => {
     if (!(error instanceof CliError))
@@ -118,6 +119,7 @@ export const proposalRegistry = (store) => {
     const registry = emptyProposalRegistry(store);
     for (const kind of [
         relationshipKind(store),
+        relationshipUpdateKind(store),
         keyDocumentKind(store),
         factKind(store),
         memoryKind(store),

package/dist/store/decisions.d.ts

@@ -1,6 +1,7 @@
 /**
  * Who proposed something waiting for the owner. `unknown` is a suggestion that names no author, such as an
- * unconfirmed link written without provenance: only the owner decides it.
+ * unconfirmed link written without provenance: only the owner decides it. `verified: false` is a bot named only by
+ * free text anyone could write, as an old suggested link's provenance: only the owner decides that one too.
  */
 export type Proposer = {
     type: "person";
@@ -10,6 +11,7 @@ export type Proposer = {
     id: string;
     name: string;
     kind: "agent" | "rule";
+    verified?: false;
 } | {
     type: "unknown";
 };

package/dist/store/decisions.js

@@ -20,6 +20,8 @@ export const mayDecide = (row, by, policy = DEFAULT_DECISION_POLICY) => {
     const proposer = row.proposedBy;
     if (proposer.type === "unknown")
         return refuse("permission_error", "proposal.owner-only", "this proposal names no author; only the owner decides it");
+    if (proposer.type === "bot" && proposer.verified === false)
+        return refuse("permission_error", "proposal.owner-only", `${proposer.name} is named only by an old link's provenance; only the owner decides it`);
     if (proposer.type === "bot" && proposer.kind === "rule" && policy.ruleProposalsOwnerOnly)
         return refuse("permission_error", "proposal.owner-only", `proposed by ${proposer.name}: only the owner decides it`);
     if (proposer.type === "bot" && proposer.kind === "agent" && botKey(proposer.name) === botKey(by.bot))
@@ -39,7 +41,11 @@ export const assertMayWithdraw = (row, by) => {
     if (by === "owner")
         return;
     const proposer = row.proposedBy;
-    if (row.proposed && proposer.type === "bot" && proposer.kind === "agent" && botKey(proposer.name) === botKey(by.bot))
+    if (row.proposed &&
+        proposer.type === "bot" &&
+        proposer.kind === "agent" &&
+        proposer.verified !== false &&
+        botKey(proposer.name) === botKey(by.bot))
         return;
     throw new CliError("permission_error", `only the owner removes or reverses ${row.id}`, {
         reason: "proposal.owner-only",

package/dist/store/index.d.ts

@@ -1,5 +1,6 @@
 export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextEvidenceSender, ContextSource, } from "../context/evidence.js";
 export { FACT_STATUSES, FACT_TYPES, MEMORY_KINDS, MEMORY_SCOPES, MEMORY_STATUSES, TASK_TYPES, WORK_TASK_TYPES, } from "../domain/knowledge.js";
+export type { RefState, RefSummary, RefSummaryKind, RefsStore } from "../domain/ref-summaries.js";
 export type { TagConsolidationApplyOptions, TagConsolidationOptions, TagConsolidationPreview, TagConsolidationReceipt, TagConsolidationStore, } from "../domain/tag-consolidation.js";
 export type { TagRedirectIndex, TagRedirectResolution, TagRedirectSnapshot } from "../domain/tag-redirects.js";
 export { createTagRedirectIndex } from "../domain/tag-redirects.js";
@@ -51,7 +52,7 @@ export { type NearestNote, NOTE_FIELDS, type NoteChunkToEmbed, type NoteHit, typ
 export type { FileNoteInput, Link, LinkInput, LinkListFilter, Note, NoteFolder, NotesStore, NoteTag, } from "./sqlite/notes.js";
 export type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
 export { PROPOSAL_STATUSES, type ProposalInput, type ProposedAction, type ProposedActionsStore, proposerOfAction, } from "./sqlite/proposed-actions.js";
-export type { LinkDecision } from "./sqlite/relation-proposals.js";
+export type { LinkDecision, RelationUpdate } from "./sqlite/relation-proposals.js";
 export { fillSearchIndex, resetSearchIndex, type SearchIndexFill, type SearchIndexState, searchIndexState, } from "./sqlite/search-index.js";
 export type { SyncStateSave } from "./sqlite/sync.js";
 export type { TagCreationOptions, TagCreationReview } from "./sqlite/tag-creation.js";

package/dist/store/sqlite/email-locations.d.ts

@@ -23,7 +23,8 @@ export declare const locate: (database: CacheDatabase, accountId: number, emailI
 export declare const folderEmails: (database: CacheDatabase, accountId: number, folder: string, uidvalidity: string) => FolderEmail[];
 /**
  * An email stored from its first bytes only (`metadata.partial`): a sync reads it whole and clears the mark.
- * `partialEmails` lists an account's live ones newest first, with how many there are in all.
+ * `partialEmails` lists an account's live ones newest first, with how many there are in all; one given up on
+ * (`partial.stuck`) is left out and only counted, so it never holds back newer ones. Its newest location comes first.
  */
 export interface PartialEmail {
     externalId: string;
@@ -35,6 +36,26 @@ export interface PartialEmail {
 export declare const partialEmails: (database: CacheDatabase, accountId: number, limit: number) => {
     emails: PartialEmail[];
     total: number;
+    stuck: number;
 };
+/** Replaces a partial email's `metadata.partial`, as a failed read records itself; a whole email is left alone. */
+export declare const markPartial: (database: CacheDatabase, accountId: number, externalId: string, mark: Metadata) => {
+    changes: number;
+};
+export interface PartialMailStore {
+    partialEmails(accountId: number, limit: number): Promise<{
+        emails: PartialEmail[];
+        total: number;
+        stuck: number;
+    }>;
+    /** Records a failed read of a partial email in its `metadata.partial`; a whole email is left alone. */
+    markPartial(accountId: number, externalId: string, mark: Metadata): Promise<void>;
+}
+export declare const partialMail: (database: CacheDatabase) => PartialMailStore;
+/**
+ * A live email stored whole, which a partial copy must not replace: a server search checks what is held before its
+ * slow read, and a sync in another process may store the email whole in between.
+ */
+export declare const storedWhole: (database: CacheDatabase, emailId: number) => boolean;
 export declare const setLocations: (database: CacheDatabase, accountId: number, folder: string, uidvalidity: string, found: ReadonlyMap<string, number[]>) => number;
 export declare const forgetLocations: (database: CacheDatabase, accountId: number, folder: string, uidvalidity: string, uids: number[]) => void;

package/dist/store/sqlite/email-locations.js

@@ -1,4 +1,5 @@
 import { fromJson } from "./events.js";
+import { write } from "./transaction.js";
 export const locate = (database, accountId, emailId, where) => database
     .prepare(`INSERT OR REPLACE INTO email_locations (mailbox_id, uidvalidity, uid, email_id)
          SELECT id, ?, ?, ? FROM mailboxes WHERE account_id = ? AND external_id = ?`)
@@ -26,14 +27,22 @@ export const partialEmails = (database, accountId, limit) => {
     const rows = database
         .prepare(`SELECT e.external_id, t.external_id AS thread, coalesce(e.received_at, e.sent_at) AS at, e.metadata,
          count(*) OVER () AS total,
-         (SELECT json_group_array(json_object('folder', b.external_id, 'uidvalidity', l.uidvalidity, 'uid', l.uid))
-            FROM email_locations l JOIN mailboxes b ON b.id = l.mailbox_id WHERE l.email_id = e.id) AS places
+         (SELECT json_group_array(json_object('folder', folder, 'uidvalidity', uidvalidity, 'uid', uid))
+            FROM (SELECT b.external_id AS folder, l.uidvalidity, l.uid
+                    FROM email_locations l JOIN mailboxes b ON b.id = l.mailbox_id
+                    WHERE l.email_id = e.id ORDER BY l.rowid DESC)) AS places
        FROM emails e JOIN email_threads t ON t.id = e.email_thread_id
        WHERE e.account_id = ? AND e.deleted_at IS NULL AND json_extract(e.metadata, '$.partial') IS NOT NULL
+         AND json_extract(e.metadata, '$.partial.stuck') IS NULL
        ORDER BY at DESC, e.id DESC LIMIT ?`)
         .all(accountId, limit);
+    const stuck = database
+        .prepare(`SELECT count(*) AS n FROM emails WHERE account_id = ? AND deleted_at IS NULL
+         AND json_extract(metadata, '$.partial.stuck') IS NOT NULL`)
+        .get(accountId);
     return {
         total: rows.length ? Number(rows[0]?.total) : 0,
+        stuck: Number(stuck?.n ?? 0),
         emails: rows.map((row) => ({
             externalId: String(row.external_id),
             threadExternalId: String(row.thread),
@@ -47,6 +56,24 @@ export const partialEmails = (database, accountId, limit) => {
         })),
     };
 };
+/** Replaces a partial email's `metadata.partial`, as a failed read records itself; a whole email is left alone. */
+export const markPartial = (database, accountId, externalId, mark) => database
+    .prepare(`UPDATE emails SET metadata = json_set(metadata, '$.partial', json(?)) WHERE account_id = ? AND external_id = ?
+         AND json_extract(metadata, '$.partial') IS NOT NULL`)
+    .run(JSON.stringify(mark), accountId, externalId);
+export const partialMail = (database) => ({
+    partialEmails: async (accountId, limit) => partialEmails(database, accountId, limit),
+    markPartial: async (accountId, externalId, mark) => {
+        write(database, () => markPartial(database, accountId, externalId, mark));
+    },
+});
+/**
+ * A live email stored whole, which a partial copy must not replace: a server search checks what is held before its
+ * slow read, and a sync in another process may store the email whole in between.
+ */
+export const storedWhole = (database, emailId) => database
+    .prepare("SELECT 1 FROM emails WHERE id = ? AND deleted_at IS NULL AND json_extract(metadata, '$.partial') IS NULL")
+    .get(emailId) !== undefined;
 export const setLocations = (database, accountId, folder, uidvalidity, found) => {
     database
         .prepare(`DELETE FROM email_locations WHERE uidvalidity <> ?

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

@@ -3,13 +3,13 @@ import type { Attachment, Metadata } from "../../meetings/index.js";
 import type { Stemmer, Stemmers } from "../../search/stem.js";
 import type { CacheDatabase } from "../driver.js";
 import type { ConversationSummary, StoredHit } from "../types.js";
-import { type EmailLocationInput, type FolderEmail, type PartialEmail } from "./email-locations.js";
+import { type EmailLocationInput, type FolderEmail, type PartialMailStore } from "./email-locations.js";
 import { type MailRulesStore } from "./mail-rules.js";
 import { type AttachmentInput } from "./meetings.js";
 import type { StoreContext } from "./open.js";
 import { type SyncStateSave } from "./sync.js";
 import { type ThreadFilter } from "./thread-columns.js";
-export type { EmailLocationInput, FolderEmail, PartialEmail };
+export type { EmailLocationInput, FolderEmail, PartialEmail } from "./email-locations.js";
 export interface EmailAddress {
     address: string;
     name: string | null;
@@ -205,7 +205,7 @@ export interface SenderScore {
     demoted?: boolean;
 }
 /** Mail in tables of its own: threads, emails, recipients and mailboxes, keyed by account and Message-ID. */
-export interface MailStore {
+export interface MailStore extends PartialMailStore {
     saveThread(input: ThreadSave): Promise<ThreadDetails>;
     /** Several threads and sync state in one transaction: a slice of mail commits with its resume point, or not at all. */
     saveThreads(inputs: ThreadSave[], states?: SyncStateSave[]): Promise<ThreadDetails[]>;
@@ -217,10 +217,6 @@ export interface MailStore {
     emails(filter?: EmailFilter): Promise<Email[]>;
     /** Each matching email's Message-ID and mailboxes, without text or people: cheap over a whole mailbox. */
     emailRefs(filter?: Omit<EmailFilter, "limit" | "offset">): Promise<EmailRef[]>;
-    partialEmails(accountId: number, limit: number): Promise<{
-        emails: PartialEmail[];
-        total: number;
-    }>;
     /** Each matching email's sender, recipients, list, size, flag and mailboxes, oldest first; no text. */
     emailFacts(filter?: Omit<EmailFilter, "limit" | "offset">): Promise<EmailFacts[]>;
     /**

package/dist/store/sqlite/emails.js

@@ -2,7 +2,7 @@ import { formatLocator } from "../../domain/locator.js";
 import { formatReference } from "../../domain/references.js";
 import { fold, normalize } from "../normalize.js";
 import { chunkAttachments, drainEmailIndex, dropAttachmentChunks, MAIL_PIECES, queueThreads, threadPieces, titleOf, } from "./email-index.js";
-import { folderEmails, forgetLocations, locate, partialEmails, setLocations, } from "./email-locations.js";
+import { folderEmails, forgetLocations, locate, partialMail, setLocations, storedWhole, } from "./email-locations.js";
 import { markEmailsDeleted, markEmailsRestored, recountEmailThread as recount, setEmailFlags } from "./email-state.js";
 import { bool, flag, fromJson, int, page, str, toJson } from "./events.js";
 import { folded } from "./folded.js";
@@ -204,6 +204,8 @@ const saveEmail = (database, orm, accountId, threadId, mail, now) => {
     const found = database
         .prepare("SELECT id, email_thread_id FROM emails WHERE account_id = ? AND external_id = ?")
         .get(accountId, mail.externalId);
+    if (found && mail.metadata?.partial !== undefined && storedWhole(database, Number(found.id)))
+        return null;
     let emailId;
     if (found) {
         emailId = Number(found.id);
@@ -469,7 +471,7 @@ export const mailStoreOver = ({ database, orm, now }, stemmerFor = stemmerCache(
             mailboxes: JSON.parse(String(row.boxes)),
         }));
     },
-    partialEmails: async (accountId, limit) => partialEmails(database, accountId, limit),
+    ...partialMail(database),
     async emailFacts(filter = {}) {
         const [where, params] = emailWhere(filter);
         return database

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

@@ -13,6 +13,8 @@ export interface EvidenceSource {
     /** Deleted at its source since it was cited, or no longer in the store. */
     missing: boolean;
 }
+/** Each distinct reference read back, in order; one the store no longer resolves keeps its reference, `missing`. */
+export declare const sourcesOfReferences: (database: CacheDatabase, references: readonly string[]) => EvidenceSource[];
 /**
  * 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.
@@ -21,5 +23,3 @@ export declare const evidenceSourcesOf: (database: CacheDatabase, from: {
     type: string;
     id: number;
 }) => EvidenceSource[];
-/** Each distinct reference read back, in order; one the store no longer resolves keeps its reference, `missing`. */
-export declare const sourcesOfReferences: (database: CacheDatabase, references: readonly string[]) => EvidenceSource[];

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

@@ -1,83 +1,47 @@
 import { linkKind } from "./link-kinds.js";
-import { referenceOfThing, stateOfThing, storedThing, thingOf } 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",
-};
-const sourceOf = (database, thing) => {
-    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,
-    };
-};
+import { refReadsOf } from "./ref-summaries.js";
+import { referenceOfThing, storedThing } from "./things.js";
+/** A message is known by its chat here, not by the sender and time its summary title says. */
+const sourceOf = (read, ref) => ({
+    ref,
+    kind: read.kind,
+    title: read.kind === "message" ? read.in : read.title,
+    sender: read.sender,
+    at: read.at,
+    excerpt: read.excerpt,
+    tool: read.provider,
+    missing: read.state !== "available",
+});
+/** Each distinct reference read back, in order; one the store no longer resolves keeps its reference, `missing`. */
+export const sourcesOfReferences = (database, references) => [...refReadsOf(database, references, { excerpt: true })].map(([ref, read]) => sourceOf(read, ref));
+const GONE_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) => sourceOf(database, storedThing(link.to_type, link.to_id)));
-const thingNamed = (database, reference) => {
-    try {
-        return thingOf(database, reference);
-    }
-    catch {
-        return undefined;
-    }
+export const evidenceSourcesOf = (database, from) => {
+    const cited = 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);
+        return { type: thing.type, ref: referenceOfThing(database, thing) };
+    });
+    const reads = refReadsOf(database, cited.flatMap(({ ref }) => ref ?? []), { excerpt: true });
+    return cited.map(({ type, ref }) => {
+        const read = ref === undefined ? undefined : reads.get(ref);
+        if (ref !== undefined && read !== undefined)
+            return sourceOf(read, ref);
+        return {
+            ref: null,
+            kind: GONE_KIND[type] ?? type,
+            title: null,
+            sender: null,
+            at: null,
+            excerpt: null,
+            tool: null,
+            missing: true,
+        };
+    });
 };
-/** Each distinct reference read back, in order; one the store no longer resolves keeps its reference, `missing`. */
-export const sourcesOfReferences = (database, references) => [...new Set(references)].map((reference) => {
-    const thing = thingNamed(database, reference);
-    if (thing)
-        return { ...sourceOf(database, thing), ref: reference };
-    return {
-        ref: reference,
-        kind: reference.startsWith("msg:") ? "message" : reference.split(":")[0] || "unknown",
-        title: null,
-        sender: null,
-        at: null,
-        excerpt: null,
-        tool: null,
-        missing: true,
-    };
-});

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

@@ -1,17 +1,17 @@
 import { type QueryAst } from "@wirecat/cli-base/query";
 import { type Decider } from "../decisions.js";
 import type { AccountKey } from "../types.js";
-import { RELATION_KINDS } from "./link-kinds.js";
 import { type MeetingProjectsStore } from "./meeting-projects.js";
 import type { Author } from "./memories.js";
 import { type Link } from "./notes.js";
 import type { StoreContext } from "./open.js";
 import type { ProposedAction } from "./proposed-actions.js";
-import { type LinkDecision } from "./relation-proposals.js";
+import { type KnowledgeRelation, type LinkDecision, type RelateInput, type RelationUpdate } from "./relation-proposals.js";
 import type { TagCreationOptions } from "./tag-creation.js";
 import { type Label, type TagKind, type TagRow } from "./tags.js";
 import { type ThingState } from "./things.js";
 import { type VocabularyStore } from "./vocabulary.js";
+export type { KnowledgeRelation, RelateInput } from "./relation-proposals.js";
 export type { Label } from "./tags.js";
 export type KnowledgeTarget = {
     type: "message";
@@ -90,18 +90,6 @@ export interface Project {
     scope: (typeof SCOPES)[number];
     createdAt: string;
 }
-export interface KnowledgeRelation {
-    id: string;
-    from: string;
-    to: string;
-    kind: (typeof RELATION_KINDS)[number];
-    role: string | null;
-    evidence: string | null;
-    confirmed: boolean;
-    provenance: string | null;
-    confidenceCategory: "owner-confirmed" | "weak";
-    createdAt: string;
-}
 export interface Reminder {
     id: string;
     task: string;
@@ -199,9 +187,24 @@ export interface KnowledgeStore extends VocabularyStore, MeetingProjectsStore {
         to: string;
         kind: KnowledgeRelation["kind"];
         role?: string;
+        purpose?: string;
         evidence?: string[];
         reason?: string;
     }, by: Exclude<Author, "owner">): Promise<ProposedAction>;
+    /** The owner sets a relationship's role and purpose; `null` clears one. */
+    updateRelation(key: KnowledgeScope, id: string, input: RelationUpdate & {
+        by: "owner";
+    }): Promise<KnowledgeRelation>;
+    /** An agent's change is a `relationship_update` proposal for the owner; the same pending change is answered again. */
+    updateRelation(key: KnowledgeScope, id: string, input: RelationUpdate & {
+        by: Exclude<Author, "owner">;
+        reason?: string;
+    }): Promise<ProposedAction>;
+    /** Decides a `relationship_update` proposal; a confirmed one changes the relationship in the same transaction. */
+    decideRelationUpdate(id: string, decision: LinkDecision): Promise<{
+        proposal: ProposedAction;
+        relation: KnowledgeRelation | null;
+    }>;
     /** Decides a stored `relationship` or `key_document` proposal; the link and the decision land together. */
     decideLinkProposal(id: string, decision: LinkDecision): Promise<{
         proposal: ProposedAction;
@@ -229,13 +232,4 @@ export interface KnowledgeStore extends VocabularyStore, MeetingProjectsStore {
     }): Promise<Reminder[]>;
     acknowledgeReminder(key: AccountKey, id: string, receipt: string): Promise<Reminder>;
 }
-export interface RelateInput {
-    from: string;
-    to: string;
-    kind: KnowledgeRelation["kind"];
-    role?: string;
-    evidence?: string;
-    confirmed?: boolean;
-    provenance?: string;
-}
 export declare const knowledgeStoreOver: (context: StoreContext) => KnowledgeStore;