@wirecat/cli-core 0.548.0 → 0.550.0

package/dist/store/sqlite/knowledge.js

@@ -15,7 +15,7 @@ import { meetingProjectsStoreOver } from "./meeting-projects.js";
 import { holdingText } from "./note-index.js";
 import { insertLink, linkOf } from "./notes.js";
 import { queryFilter } from "./query-filter.js";
-import { relationProposalsOver } from "./relation-proposals.js";
+import { relationOf, relationProposalsOver, } from "./relation-proposals.js";
 import { addTags as addThingTags, canonicalTagNamed, createTag, labelsOf, liveTagging, removeTags as removeThingTags, setMainTopic, } from "./tags.js";
 import { INBOX_KEY_LENGTH, TASK_KEY_PREFIXES } from "./task-keys.js";
 import { inboxKey, taskAccountOf, taskIdOf, taskRowOf } from "./tasks.js";
@@ -221,18 +221,6 @@ export const knowledgeStoreOver = (context) => {
         scope: row.scope,
         createdAt: iso(row.created_at),
     });
-    const relationOf = (link) => ({
-        id: link.id,
-        from: link.from,
-        to: String(link.to),
-        kind: link.kind,
-        role: link.role,
-        evidence: link.evidence,
-        confirmed: link.confirmed,
-        provenance: link.provenance,
-        confidenceCategory: link.confirmed ? "owner-confirmed" : "weak",
-        createdAt: link.createdAt,
-    });
     const proposals = relationProposalsOver(context);
     const RELATIONS = `SELECT * FROM links WHERE kind IN (${RELATION_KINDS.map(linkKind).join(",")}) AND to_id IS NOT NULL`;
     const relation = (id) => {
@@ -561,6 +549,7 @@ export const knowledgeStoreOver = (context) => {
                 origin: confirmed ? "owner" : "suggested",
                 confirmed,
                 ...(input.role === undefined ? {} : { role: input.role }),
+                ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
                 ...(input.evidence === undefined ? {} : { evidence: input.evidence }),
                 ...(input.provenance === undefined ? {} : { provenance: input.provenance }),
             })));
@@ -573,6 +562,17 @@ export const knowledgeStoreOver = (context) => {
                 });
             return proposals.propose(from, input, by);
         },
+        updateRelation: (async (key, id, input) => {
+            checked(key);
+            const link = linkOf(database, relation(id));
+            if (input.by === "owner")
+                return relationOf(proposals.update(link, input));
+            return proposals.proposeUpdate(link, input, input.by);
+        }),
+        decideRelationUpdate: async (id, decision) => {
+            const { proposal, link } = proposals.decideUpdate(id, decision);
+            return { proposal, relation: link && relationOf(link) };
+        },
         decideLinkProposal: async (id, decision) => proposals.decideProposal(id, decision),
         decideSuggestedLink: async (id, decision) => proposals.decideLink(id, decision),
         relations: async (key, reference) => {

package/dist/store/sqlite/manifest.js

@@ -57,6 +57,8 @@ export const MANIFEST = [
     { name: "20261031230945_version-41-task-fields", version: 41, minCompatible: 34 },
     { name: "20261101002523_version-42-task-revision", version: 42, minCompatible: 34 },
     { name: "20261101011859_version-43-memory-project", version: 43, minCompatible: 34 },
+    { name: "20261102050533_version-44-relationship-purpose", version: 44, minCompatible: 34 },
+    { name: "20261102050534_version-44-suggested-links-move", version: 44, minCompatible: 34 },
 ];
 export const generatedMigrations = (manifest = MANIFEST, generated = GENERATED) => {
     const migrations = [];

package/dist/store/sqlite/migrations.generated.js

@@ -877,5 +877,17 @@ export const GENERATED = [
             "ALTER TABLE `memories` ADD `project_id` integer REFERENCES projects(id);",
             "CREATE INDEX `memories_by_project_id` ON `memories` (`project_id`);"
         ]
+    },
+    {
+        "name": "20261102050533_version-44-relationship-purpose",
+        "statements": [
+            "ALTER TABLE `links` ADD `purpose` text;"
+        ]
+    },
+    {
+        "name": "20261102050534_version-44-suggested-links-move",
+        "statements": [
+            "-- A suggestion's references (chat:, msg:) need the store's own encoding, which SQL cannot write, so the next writable\n-- open moves the unconfirmed agent and rule links into `proposed_actions` and deletes this key (moveSuggestedLinks).\nINSERT OR REPLACE INTO store_settings (key, value, at) VALUES ('suggested_links_to_move', '1', unixepoch() * 1000);"
+        ]
     }
 ];

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

@@ -56,6 +56,8 @@ export interface Link {
     origin: (typeof LINK_SOURCES)[number];
     targetText: string | null;
     role: string | null;
+    /** What a chat is for in a project, from the purposes memo's config lists; `null` means `work`. */
+    purpose: string | null;
     evidence: string | null;
     provenance: string | null;
     confirmed: boolean;
@@ -79,6 +81,7 @@ export interface LinkInput {
     anchor?: string;
     origin?: (typeof LINK_ORIGINS)[number];
     role?: string;
+    purpose?: string;
     evidence?: string;
     provenance?: string;
     confirmed?: boolean;
@@ -194,6 +197,8 @@ export declare const requiredThing: (database: CacheDatabase, reference: string,
  * and only a name some note is waiting for costs more.
  */
 export declare const resolvePersonLinks: (database: CacheDatabase, names: (string | null | undefined)[]) => void;
+/** The store keeps no list of purposes: memo's config holds it, and checks a purpose before it gets here. */
+export declare const purposeOf: (purpose: string) => string;
 /** Writes one link; an identical resolved link is answered instead of doubled. */
 export declare const insertLink: (context: StoreContext, input: LinkInput) => Link;
 export declare const notesStoreOver: (context: StoreContext) => Omit<NotesStore, keyof NoteSearch>;

package/dist/store/sqlite/notes.js

@@ -87,6 +87,7 @@ export const linkOf = (database, row) => {
         origin: row.source,
         targetText: row.target_text == null ? null : String(row.target_text),
         role: row.role == null ? null : String(row.role),
+        purpose: row.purpose == null ? null : String(row.purpose),
         evidence: row.evidence == null ? null : String(row.evidence),
         provenance: metadata.provenance ?? null,
         confirmed: Number(row.confirmed) === 1,
@@ -164,6 +165,8 @@ const ownerLink = (input) => {
         });
     return input;
 };
+/** The store keeps no list of purposes: memo's config holds it, and checks a purpose before it gets here. */
+export const purposeOf = (purpose) => textOf(purpose, "a purpose", 100);
 /** Writes one link; an identical resolved link is answered instead of doubled. */
 export const insertLink = (context, input) => {
     const { database, now } = context;
@@ -187,8 +190,9 @@ export const insertLink = (context, input) => {
     const provenance = input.provenance === undefined ? undefined : textOf(input.provenance, "provenance", 2000);
     const row = database
         .prepare("INSERT INTO links (from_type, from_id, to_type, to_id, kind, anchor, source, target_text, target_folded, role, evidence, " +
-        "metadata, confirmed, created_at, author, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id")
-        .get(from.type, from.id, to?.type ?? null, to?.id ?? null, kind, input.anchor ?? null, origin, targetText, targetText === null ? null : targetKey(targetText), input.role === undefined ? null : textOf(input.role, "a role", 200), input.evidence === undefined ? null : textOf(input.evidence, "evidence", 2000), provenance === undefined ? null : JSON.stringify({ provenance }), input.confirmed === false ? 0 : 1, at, origin === "owner" ? "owner" : null, at);
+        "metadata, confirmed, created_at, author, updated_at, purpose) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) " +
+        "RETURNING id")
+        .get(from.type, from.id, to?.type ?? null, to?.id ?? null, kind, input.anchor ?? null, origin, targetText, targetText === null ? null : targetKey(targetText), input.role === undefined ? null : textOf(input.role, "a role", 200), input.evidence === undefined ? null : textOf(input.evidence, "evidence", 2000), provenance === undefined ? null : JSON.stringify({ provenance }), input.confirmed === false ? 0 : 1, at, origin === "owner" ? "owner" : null, at, input.purpose === undefined ? null : purposeOf(input.purpose));
     if (to === null && targetText !== null)
         resolveKey(database, targetKey(targetText));
     return linkOf(database, database.prepare("SELECT * FROM links WHERE id = ?").get(Number(row?.id)));

package/dist/store/sqlite/open-store.js

@@ -16,6 +16,7 @@ import { loadProviders } from "./providers.js";
 import { assertReadCompatible } from "./read-compatibility.js";
 import { stemsState } from "./stems.js";
 import { fillStems, followDefaultStemmers } from "./stems-fill.js";
+import { moveSuggestedLinks } from "./suggested-links.js";
 import { fillVectorIndexes } from "./vector-index.js";
 export const BACKFILL_ON_OPEN = 5_000;
 const NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS"]);
@@ -55,6 +56,7 @@ export const openStoreContext = async ({ path, env, now = Date.now, command, ver
             fillFiles(database, now);
             fillFolded(database);
             fillJoinKeys(database);
+            moveSuggestedLinks(database, now);
             const pending = pendingNormalization(database);
             if (pending > 0 && pending <= BACKFILL_ON_OPEN)
                 backfillNormalized(database);

package/dist/store/sqlite/proposed-actions.d.ts

@@ -81,7 +81,7 @@ type ProposalOperations = Omit<{
     proposer(id: string): Proposer;
 };
 /** Who proposed an action, for `mayDecide`. */
-export declare const proposerOfAction: ({ proposedBy }: ProposedAction) => Proposer;
+export declare const proposerOfAction: ({ proposedBy, payload }: ProposedAction) => Proposer;
 export declare const proposalOperationsOver: (context: StoreContext) => ProposalOperations;
 export declare const proposedActionsStoreOver: (context: StoreContext) => ProposedActionsStore;
 export {};

package/dist/store/sqlite/proposed-actions.js

@@ -20,11 +20,19 @@ const STATUS = `CASE WHEN p.status = 'approved' AND p.kind IN ('${MEETING_FINDIN
 const NAMED = `SELECT p.*, ${STATUS} AS shown_status, b.name AS proposer_name, b.kind AS proposer_kind FROM proposed_actions p ` +
     "LEFT JOIN bots b ON p.proposed_by_type = 'bot' AND b.id = p.proposed_by_id";
 /** Who proposed an action, for `mayDecide`. */
-export const proposerOfAction = ({ proposedBy }) => proposedBy.type === "person"
+export const proposerOfAction = ({ proposedBy, payload }) => proposedBy.type === "person"
     ? { type: "person", id: proposedBy.id }
     : proposedBy.name === null
         ? { type: "unknown" }
-        : { type: "bot", id: proposedBy.id, name: proposedBy.name, kind: proposedBy.kind ?? "agent" };
+        : {
+            type: "bot",
+            id: proposedBy.id,
+            name: proposedBy.name,
+            kind: proposedBy.kind ?? "agent",
+            ...(movedSuggestion(payload) ? { verified: false } : {}),
+        };
+/** A suggestion moved from `links` names its bot only as the link's provenance text said it (store version 44). */
+const movedSuggestion = (payload) => typeof payload === "object" && payload !== null && "suggestedLink" in payload;
 export const proposalOperationsOver = (context) => {
     const { database, now } = context;
     const actionOf = (row) => {

package/dist/store/sqlite/ref-summaries.d.ts

@@ -0,0 +1,17 @@
+import { type RefSummary } from "../../domain/ref-summaries.js";
+import type { CacheDatabase } from "../driver.js";
+/** A summary plus what an evidence reader shows beside it; `summaries` drops the extra fields. */
+export interface RefRead extends RefSummary {
+    sender: string | null;
+    excerpt: string | null;
+}
+/**
+ * Every ref read back in one statement per kind present, keyed by the text passed and in its order. A bad ref is
+ * `unknown` and a ref the store lacks is `unavailable`: one bad row must not fail a page of them.
+ */
+export declare const refReadsOf: (database: CacheDatabase, texts: readonly string[], { excerpt }?: {
+    excerpt?: boolean;
+}) => Map<string, RefRead>;
+export declare const refSummariesOf: (database: CacheDatabase, texts: readonly string[], options?: {
+    excerpt?: boolean;
+}) => Map<string, RefSummary>;

package/dist/store/sqlite/ref-summaries.js

@@ -0,0 +1,378 @@
+import { filesAccountSql, providerLabel, providerNamed } from "../../domain/providers.js";
+import { oneLine } from "../../domain/ref-summaries.js";
+import { formatReference, parseReference } from "../../domain/references.js";
+const EXCERPT_CHARS = 280;
+const TITLE_CHARS = 120;
+const MEMORY_TITLE_CHARS = 80;
+/** SQLite's parameter limit is per statement; a long page is read in slices, still one statement per slice. */
+const SLICE = 500;
+const flat = (value) => {
+    if (value == null)
+        return null;
+    const text = oneLine(String(value));
+    return text === "" ? null : text;
+};
+const cut = (text, chars) => text === null || text.length <= chars ? text : `${text.slice(0, chars - 1)}…`;
+const iso = (at) => (at === null ? null : new Date(at).toISOString());
+const minute = (at) => iso(at)?.slice(0, 16).replace("T", " ") ?? null;
+const storeId = (text) => (/^[1-9]\d{0,15}$/.test(text) ? Number(text) : undefined);
+const bodyOr = (body, column) => (body ? column : "NULL");
+const PERSON_NAME = "coalesce(p.name, (SELECT a.name FROM aliases a WHERE a.aliasable_type = 'person' AND a.aliasable_id = p.id " +
+    "ORDER BY a.display DESC, a.id LIMIT 1), (SELECT i.name FROM identity_links l JOIN identities i " +
+    "ON i.id = l.identity_id WHERE l.person_id = p.id AND i.name IS NOT NULL ORDER BY i.id LIMIT 1))";
+/** What a row is about, by name; the owner is left out, or every owner's note would say whose it is. */
+const subjectName = (type, id) => `CASE ${type} WHEN 'person' THEN (SELECT ${PERSON_NAME} FROM persons p WHERE p.id = ${id} AND p.owner = 0) ` +
+    `WHEN 'project' THEN (SELECT name FROM projects WHERE id = ${id}) ` +
+    `WHEN 'organization' THEN (SELECT name FROM organizations WHERE id = ${id}) ` +
+    `WHEN 'account' THEN (SELECT name FROM accounts WHERE id = ${id}) END`;
+const select = (columns) => `SELECT w.n, ${["title", "holder", "sender", "at", "provider", "account", "deleted", "body"]
+    .map((column) => `${columns[column] ?? "NULL"} AS ${column}`)
+    .join(", ")}`;
+const byId = (kind, table, columns) => ({
+    kind,
+    sql: (body) => `${select(columns(body))} FROM w JOIN ${table} x ON x.id = w.k1`,
+});
+const READERS = {
+    message: {
+        kind: "message",
+        sql: (body) => `${select({
+            holder: "c.title",
+            sender: "coalesce(m.sender_name, i.name)",
+            at: "m.sent_at",
+            provider: "a.provider",
+            account: "a.external_id",
+            deleted: "m.deleted_at",
+            body: bodyOr(body, "m.text"),
+        })} FROM w JOIN accounts a ON a.provider = w.k1 AND a.external_id = w.k2 ` +
+            "JOIN chats c ON c.account_id = a.id AND c.external_id = w.k3 " +
+            "JOIN messages m ON m.chat_id = c.id AND m.external_id = w.k4 LEFT JOIN identities i ON i.id = m.sender_identity_id",
+    },
+    email: {
+        kind: "email",
+        sql: (body) => `${select({
+            title: "e.subject",
+            holder: "coalesce(e.from_name, e.from_address)",
+            sender: "coalesce(e.from_name, e.from_address)",
+            at: "e.sent_at",
+            provider: "'email'",
+            account: "a.external_id",
+            deleted: "e.deleted_at",
+            body: bodyOr(body, "coalesce(e.body_text, e.snippet)"),
+        })} FROM w JOIN accounts a ON a.provider = 'email' AND a.external_id = w.k1 ` +
+            "JOIN email_threads t ON t.account_id = a.id AND t.external_id = w.k2 " +
+            "JOIN emails e ON e.email_thread_id = t.id AND e.external_id = w.k3",
+    },
+    chat: {
+        kind: "chat",
+        sql: () => `${select({
+            title: "c.title",
+            at: "(SELECT max(sent_at) FROM messages WHERE chat_id = c.id)",
+            provider: "a.provider",
+            account: "a.external_id",
+        })} FROM w JOIN accounts a ON a.provider = w.k1 AND a.external_id = w.k2 ` +
+            "JOIN chats c ON c.account_id = a.id AND c.external_id = w.k3",
+    },
+    email_thread: {
+        kind: "email_thread",
+        sql: () => `${select({
+            title: "t.subject",
+            holder: "a.external_id",
+            at: "t.last_email_at",
+            provider: "'email'",
+            account: "a.external_id",
+            deleted: "t.deleted_at",
+        })} FROM w JOIN accounts a ON a.provider = 'email' AND a.external_id = w.k1 ` +
+            "JOIN email_threads t ON t.account_id = a.id AND t.external_id = w.k2",
+    },
+    contact: {
+        kind: "contact",
+        sql: () => `${select({ title: "coalesce(i.name, '@' || i.username)", provider: "i.provider" })} ` +
+            "FROM w JOIN identities i ON i.provider = w.k1 AND i.external_id = w.k2",
+    },
+    folder: {
+        kind: "folder",
+        sql: () => `${select({ title: "a.name", provider: "a.provider", account: "a.external_id" })} ` +
+            `FROM w JOIN accounts a ON a.id = w.k1 AND ${filesAccountSql("a.provider")}`,
+    },
+    task: {
+        kind: "task",
+        // A task moved to another project took a new key there; its old key still names it, as in `taskRowOf`.
+        sql: (body) => `${select({
+            title: "CASE WHEN x.key IS NULL THEN x.title ELSE x.key || ' · ' || x.title END",
+            holder: "p.name",
+            at: "x.due_at",
+            deleted: "x.deleted_at",
+            body: bodyOr(body, "x.description"),
+        })} FROM w JOIN tasks x ON x.id = coalesce(` +
+            "(SELECT id FROM tasks WHERE package_id = w.k1 OR key = w.k1 ORDER BY id LIMIT 1), " +
+            "(SELECT task_id FROM task_events WHERE kind = 'project' AND json_extract(changes, '$.key[0]') = w.k1 " +
+            "ORDER BY id DESC LIMIT 1)) LEFT JOIN projects p ON p.id = x.project_id",
+    },
+    meeting: {
+        kind: "meeting",
+        sql: (body) => `${select({
+            title: "m.title",
+            holder: "coalesce(a.name, a.external_id)",
+            sender: "r.speaker_name",
+            at: "m.started_at + coalesce(r.start_ms, 0)",
+            provider: "a.provider",
+            account: "a.external_id",
+            deleted: "coalesce(m.deleted_at, t.deleted_at)",
+            body: bodyOr(body, "CASE WHEN w.k4 IS NOT NULL THEN r.text WHEN w.k3 IS NULL THEN m.description END"),
+        })} FROM w JOIN meetings m ON m.id = w.k2 AND m.account_id = w.k1 LEFT JOIN accounts a ON a.id = m.account_id ` +
+            "LEFT JOIN meeting_transcripts t ON t.id = w.k3 AND t.meeting_id = m.id " +
+            "LEFT JOIN meeting_transcript_rows r ON r.meeting_transcript_id = t.id AND r.position = w.k4 " +
+            "WHERE (w.k3 IS NULL OR t.id IS NOT NULL) AND (w.k4 IS NULL OR r.id IS NOT NULL)",
+    },
+    event: {
+        kind: "event",
+        sql: (body) => `${select({
+            title: "x.title",
+            holder: "c.title",
+            at: "x.starts_at",
+            provider: "a.provider",
+            account: "a.external_id",
+            deleted: "x.deleted_at",
+            body: bodyOr(body, "x.description"),
+        })} FROM w JOIN events x ON x.id = w.k1 ` +
+            "LEFT JOIN calendar_entries ce ON ce.id = (SELECT min(id) FROM calendar_entries WHERE event_id = x.id) " +
+            "LEFT JOIN calendars c ON c.id = ce.calendar_id LEFT JOIN accounts a ON a.id = c.account_id",
+    },
+    document: {
+        kind: "document",
+        sql: (body) => `${select({
+            title: "coalesce(x.title, x.file_name)",
+            at: "coalesce(x.external_updated_at, x.updated_at)",
+            provider: "a.provider",
+            account: "a.external_id",
+            deleted: "x.deleted_at",
+            body: bodyOr(body, "x.body"),
+        })} FROM w JOIN documents x ON x.id = w.k1 LEFT JOIN accounts a ON a.id = x.account_id`,
+    },
+    note: byId("note", "notes", (body) => ({
+        title: "x.title",
+        holder: subjectName("x.notable_type", "x.notable_id"),
+        at: "x.updated_at",
+        provider: "'notes'",
+        deleted: "x.deleted_at",
+        body: bodyOr(body, "x.body"),
+    })),
+    person: {
+        kind: "person",
+        sql: () => `${select({ title: PERSON_NAME })} FROM w JOIN persons p ON p.id = w.k1`,
+    },
+    organization: byId("organization", "organizations", () => ({ title: "x.name", deleted: "x.deleted_at" })),
+    project: byId("project", "projects", () => ({
+        title: "CASE WHEN x.key IS NULL THEN x.name ELSE x.key || ' · ' || x.name END",
+        deleted: "x.deleted_at",
+    })),
+    memory: byId("memory", "memories", (body) => ({
+        title: "substr(x.body, 1, 400)",
+        holder: subjectName("x.subject_type", "x.subject_id"),
+        at: "x.created_at",
+        deleted: "x.deleted_at",
+        body: bodyOr(body, "x.body"),
+    })),
+    fact: byId("fact", "facts", (body) => ({
+        title: "substr(x.statement, 1, 400)",
+        holder: subjectName("x.subject_type", "x.subject_id"),
+        at: "x.created_at",
+        deleted: "x.deleted_at",
+        body: bodyOr(body, "x.statement"),
+    })),
+    bot: byId("bot", "bots", () => ({ title: "x.name" })),
+};
+/** Mail saved before the mail tables existed is still messages, so a miss there is read again as a message. */
+const FALLBACK = { email: "message", email_thread: "chat" };
+const route = (reference) => {
+    switch (reference.type) {
+        case "message":
+            return reference.provider === "email"
+                ? { reader: "email", keys: [reference.account, reference.chat, reference.message] }
+                : { reader: "message", keys: [reference.provider, reference.account, reference.chat, reference.message] };
+        case "chat":
+            return reference.provider === "email"
+                ? { reader: "email_thread", keys: [reference.account, reference.chat] }
+                : { reader: "chat", keys: [reference.provider, reference.account, reference.chat] };
+        case "contact":
+            return { reader: "contact", keys: [reference.provider, reference.id] };
+        case "meeting":
+            return {
+                reader: "meeting",
+                keys: [reference.accountId, reference.meetingId, reference.transcriptId ?? null, reference.cuePosition ?? null],
+            };
+        case "task":
+            return { reader: "task", keys: [reference.id] };
+        case "entity":
+            return undefined;
+        case "folder": {
+            const id = storeId(reference.id);
+            return id === undefined ? undefined : { reader: "folder", keys: [id] };
+        }
+        default: {
+            const id = storeId(reference.id);
+            return id === undefined ? undefined : { reader: reference.type, keys: [id] };
+        }
+    }
+};
+const keysOf = (reader, reference) => {
+    if (reader === "message" && reference.type === "message")
+        return [reference.provider, reference.account, reference.chat, reference.message];
+    if (reader === "chat" && reference.type === "chat")
+        return [reference.provider, reference.account, reference.chat];
+    return [];
+};
+const kindOfReference = (reference) => reference.type === "entity"
+    ? "unknown"
+    : reference.type === "message" && reference.provider === "email"
+        ? "email"
+        : reference.type === "chat" && reference.provider === "email"
+            ? "email_thread"
+            : reference.type;
+const runReader = (database, reader, wanted, body) => {
+    const found = new Map();
+    const width = wanted[0]?.keys.length ?? 0;
+    const names = Array.from({ length: width }, (_, at) => `k${at + 1}`);
+    for (let start = 0; start < wanted.length; start += SLICE) {
+        const slice = wanted.slice(start, start + SLICE);
+        const values = slice.map(() => `(${["?", ...names.map(() => "?")].join(", ")})`).join(", ");
+        const sql = `WITH w(n, ${names.join(", ")}) AS (VALUES ${values}) ${reader.sql(body)}`;
+        const parameters = slice.flatMap((one, at) => [start + at, ...one.keys]);
+        for (const row of database.prepare(sql).all(...parameters)) {
+            const n = Number(row.n);
+            if (found.has(n))
+                continue;
+            found.set(n, {
+                title: flat(row.title),
+                holder: flat(row.holder),
+                sender: flat(row.sender),
+                at: row.at == null ? null : Number(row.at),
+                provider: row.provider == null ? null : String(row.provider),
+                account: row.account == null ? null : String(row.account),
+                deleted: row.deleted != null,
+                body: row.body == null ? null : String(row.body),
+            });
+        }
+    }
+    return found;
+};
+const toolOf = (provider) => (provider === null ? null : (providerNamed(provider)?.command ?? null));
+const refOfAccount = (reference) => reference.type === "message" || reference.type === "chat"
+    ? { provider: reference.provider, account: reference.account }
+    : reference.type === "contact"
+        ? { provider: reference.provider, account: null }
+        : { provider: null, account: null };
+const titleOf = (kind, reference, found) => {
+    switch (kind) {
+        case "message": {
+            const words = [found.sender, minute(found.at)].filter((one) => one !== null);
+            return words.length === 0 ? null : words.join(" · ");
+        }
+        case "memory":
+        case "fact":
+            return cut(found.title, MEMORY_TITLE_CHARS);
+        case "folder":
+            return reference.type === "folder" && reference.path !== null && found.title !== null
+                ? `${found.title}/${reference.path}`
+                : found.title;
+        default:
+            return found.title;
+    }
+};
+const inOf = (kind, found) => found.holder ??
+    ((kind === "chat" || kind === "contact" || kind === "document") && found.provider !== null
+        ? providerLabel(found.provider)
+        : null);
+const readOf = (wanted, found, reader, excerpt) => {
+    const ref = formatReference(wanted.reference);
+    if (found === undefined || reader === undefined) {
+        const { provider, account } = refOfAccount(wanted.reference);
+        return {
+            ref,
+            kind: kindOfReference(wanted.reference),
+            title: null,
+            in: null,
+            at: null,
+            provider,
+            account,
+            tool: toolOf(provider),
+            state: "unavailable",
+            sender: null,
+            excerpt: null,
+        };
+    }
+    const state = found.deleted ? "deleted" : "available";
+    return {
+        ref,
+        kind: reader.kind,
+        title: cut(titleOf(reader.kind, wanted.reference, found), TITLE_CHARS),
+        in: cut(inOf(reader.kind, found), TITLE_CHARS),
+        at: iso(found.at),
+        provider: found.provider,
+        account: found.account,
+        tool: toolOf(found.provider),
+        state,
+        sender: found.sender,
+        excerpt: excerpt && state === "available" ? cut(flat(found.body), EXCERPT_CHARS) : null,
+    };
+};
+const unknown = (text) => ({
+    ref: text.trim(),
+    kind: "unknown",
+    title: null,
+    in: null,
+    at: null,
+    provider: null,
+    account: null,
+    tool: null,
+    state: "unavailable",
+    sender: null,
+    excerpt: null,
+});
+const parsed = (text) => {
+    try {
+        return parseReference(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Every ref read back in one statement per kind present, keyed by the text passed and in its order. A bad ref is
+ * `unknown` and a ref the store lacks is `unavailable`: one bad row must not fail a page of them.
+ */
+export const refReadsOf = (database, texts, { excerpt = false } = {}) => {
+    const reads = new Map();
+    const groups = new Map();
+    for (const text of new Set(texts)) {
+        const reference = parsed(text);
+        const routed = reference === undefined ? undefined : route(reference);
+        if (reference === undefined || routed === undefined) {
+            reads.set(text, reference === undefined ? unknown(text) : readOf({ text, reference, keys: [] }, undefined, undefined, false));
+            continue;
+        }
+        reads.set(text, unknown(text));
+        const group = groups.get(routed.reader) ?? [];
+        group.push({ text, reference, keys: routed.keys });
+        groups.set(routed.reader, group);
+    }
+    const pending = [...groups.entries()];
+    while (pending.length > 0) {
+        const [name, wanted] = pending.shift();
+        const reader = READERS[name];
+        const found = runReader(database, reader, wanted, excerpt);
+        const fallback = FALLBACK[name];
+        const missed = [];
+        for (const [n, one] of wanted.entries()) {
+            const row = found.get(n);
+            if (row === undefined && fallback !== undefined)
+                missed.push(one);
+            reads.set(one.text, readOf(one, row, reader, excerpt));
+        }
+        if (fallback !== undefined && missed.length > 0)
+            pending.push([fallback, missed.map((one) => ({ ...one, keys: keysOf(fallback, one.reference) }))]);
+    }
+    return reads;
+};
+const summaryOf = ({ sender, excerpt, ...summary }, withExcerpt) => withExcerpt ? { ...summary, excerpt } : summary;
+export const refSummariesOf = (database, texts, options = {}) => new Map([...refReadsOf(database, texts, options)].map(([text, read]) => [text, summaryOf(read, options.excerpt === true)]));

package/dist/store/sqlite/relation-proposals.d.ts

@@ -1,9 +1,35 @@
 import { type Decider } from "../decisions.js";
+import type { RELATION_KINDS } from "./link-kinds.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 Thing } from "./things.js";
+export interface KnowledgeRelation {
+    id: string;
+    from: string;
+    to: string;
+    kind: (typeof RELATION_KINDS)[number];
+    role: string | null;
+    /** What a chat is for in the project, from the purposes memo's config lists; `null` means `work`. */
+    purpose: string | null;
+    evidence: string | null;
+    confirmed: boolean;
+    provenance: string | null;
+    confidenceCategory: "owner-confirmed" | "weak";
+    createdAt: string;
+}
+export interface RelateInput {
+    from: string;
+    to: string;
+    kind: KnowledgeRelation["kind"];
+    role?: string;
+    purpose?: string;
+    evidence?: string;
+    confirmed?: boolean;
+    provenance?: string;
+}
+export declare const relationOf: (link: Link) => KnowledgeRelation;
 /** `relationship` proposals in `proposed_actions`: an agent's or a rule's, and the rejected ones a scan skips. */
 export declare const relationProposalsOver: (context: StoreContext) => {
     /** The same pending pair returns the proposal already held. */
@@ -12,10 +38,19 @@ export declare const relationProposalsOver: (context: StoreContext) => {
         to: string;
         kind: string;
         role?: string;
+        purpose?: string;
         evidence?: string[];
         reason?: string;
     }, by: Exclude<Author, "owner">) => ProposedAction;
     rejected: (link: Link, by: Decider, reason?: string) => void;
+    update: (link: Link, input: RelationUpdate) => Link;
+    proposeUpdate: (link: Link, input: RelationUpdate & {
+        reason?: string;
+    }, by: Exclude<Author, "owner">) => ProposedAction;
+    decideUpdate: (id: string, decision: LinkDecision) => {
+        proposal: ProposedAction;
+        link: Link | null;
+    };
     /**
      * Decides a stored `relationship` or `key_document` proposal in one transaction: the confirmed link and the
      * decision land together or not at all.
@@ -27,6 +62,11 @@ export declare const relationProposalsOver: (context: StoreContext) => {
     /** Decides an unconfirmed link written before proposals were stored; only the owner may, as its author is unknown. */
     decideLink: (id: string, decision: LinkDecision) => Link | null;
 };
+/** A relationship's role and purpose to set; `null` clears one. */
+export interface RelationUpdate {
+    role?: string | null;
+    purpose?: string | null;
+}
 export interface LinkDecision {
     confirm: boolean;
     by: Decider;