@wirecat/cli-core 0.547.0 → 0.549.0

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;

package/dist/store/sqlite/relation-proposals.js

@@ -1,10 +1,23 @@
 import { CliError } from "@wirecat/cli-base";
 import { assertMayDecide, deciderAuthor } from "../decisions.js";
 import { actorOfOrigin, botNamed, ownerPerson } from "./actors.js";
-import { insertLink, linkOf } from "./notes.js";
+import { insertLink, linkOf, purposeOf } from "./notes.js";
 import { proposalOperationsOver, proposerOfAction } from "./proposed-actions.js";
 import { thingOf } from "./things.js";
 import { write } from "./transaction.js";
+export const relationOf = (link) => ({
+    id: link.id,
+    from: link.from,
+    to: String(link.to),
+    kind: link.kind,
+    role: link.role,
+    purpose: link.purpose,
+    evidence: link.evidence,
+    confirmed: link.confirmed,
+    provenance: link.provenance,
+    confidenceCategory: link.confirmed ? "owner-confirmed" : "weak",
+    createdAt: link.createdAt,
+});
 /** `relationship` proposals in `proposed_actions`: an agent's or a rule's, and the rejected ones a scan skips. */
 export const relationProposalsOver = (context) => {
     const { database, now } = context;
@@ -26,6 +39,14 @@ export const relationProposalsOver = (context) => {
             "VALUES ('relationship', ?, ?, ?, ?, 'rejected', ?, ?, ?, ?, ?, ?, ?, ?)")
             .run(from?.type ?? null, from?.id ?? null, JSON.stringify({ from: link.from, to: link.to, kind: link.kind, ...(link.role ? { role: link.role } : {}) }), link.evidence, proposed.type, proposed.id, decided.type, decided.id, at, JSON.stringify({ reason: why.join(": "), link: link.id }), at, at);
     };
+    const applyUpdate = (link, input) => {
+        const changes = changesOf(input);
+        database
+            .prepare("UPDATE links SET role = CASE WHEN ? THEN ? ELSE role END, purpose = CASE WHEN ? THEN ? ELSE purpose END, " +
+            "updated_at = ? WHERE id = ?")
+            .run(Number("role" in changes), changes.role ?? null, Number("purpose" in changes), changes.purpose ?? null, now(), Number(link.id));
+        return linkOf(database, database.prepare("SELECT * FROM links WHERE id = ?").get(Number(link.id)));
+    };
     return {
         /** The same pending pair returns the proposal already held. */
         propose: (from, input, by) => {
@@ -48,6 +69,7 @@ export const relationProposalsOver = (context) => {
                         to: input.to,
                         kind: input.kind,
                         ...(input.role === undefined ? {} : { role: input.role }),
+                        ...(input.purpose === undefined ? {} : { purpose: purposeOf(input.purpose) }),
                         evidence,
                     },
                     ...(input.reason === undefined ? {} : { reason: input.reason }),
@@ -55,6 +77,53 @@ export const relationProposalsOver = (context) => {
             });
         },
         rejected: (link, by, reason) => rejected(link, by, reason),
+        update: (link, input) => write(database, () => applyUpdate(link, input)),
+        proposeUpdate: (link, input, by) => {
+            const changes = changesOf(input);
+            return write(database, () => {
+                const from = thingOf(database, link.from);
+                const held = database
+                    .prepare("SELECT id FROM proposed_actions WHERE kind='relationship_update' AND status='proposed' AND target_type=? " +
+                    "AND target_id=? AND json_extract(payload,'$.relationship')=? AND json_extract(payload,'$.changes')=json(?) " +
+                    "ORDER BY id LIMIT 1")
+                    .get(from?.type ?? null, from?.id ?? null, link.id, JSON.stringify(changes));
+                if (held)
+                    return operations.get(String(held.id));
+                return operations.propose({
+                    kind: "relationship_update",
+                    by,
+                    target: link.from,
+                    payload: {
+                        relationship: link.id,
+                        from: link.from,
+                        to: link.to,
+                        kind: link.kind,
+                        changes,
+                        before: { role: link.role, purpose: link.purpose },
+                    },
+                    ...(input.reason === undefined ? {} : { reason: input.reason }),
+                });
+            });
+        },
+        decideUpdate: (id, decision) => write(database, () => {
+            const proposal = operations.get(id);
+            if (proposal.kind !== "relationship_update")
+                throw new CliError("validation_error", `${id} is a ${proposal.kind} proposal, not a relationship change`);
+            assertMayDecide({ id, proposedBy: proposerOfAction(proposal) }, decision.by, context.decisions);
+            const author = deciderAuthor(decision.by);
+            const reason = decision.reason?.trim() || undefined;
+            if (!decision.confirm)
+                return { proposal: operations.reject(id, author, reason === undefined ? undefined : { reason }), link: null };
+            const payload = proposal.payload;
+            const row = database.prepare("SELECT * FROM links WHERE id = ?").get(Number(payload.relationship));
+            if (!row)
+                throw new CliError("not_found", `relationship ${payload.relationship} is gone`);
+            const link = applyUpdate(linkOf(database, row), payload.changes);
+            return {
+                proposal: operations.approve(id, { relationship: link.id, ...(reason === undefined ? {} : { reason }) }, author),
+                link,
+            };
+        }),
         /**
          * Decides a stored `relationship` or `key_document` proposal in one transaction: the confirmed link and the
          * decision land together or not at all.
@@ -75,6 +144,7 @@ export const relationProposalsOver = (context) => {
                 to: String(key ? payload.project : payload.to),
                 kind: key ? "related-to" : (payload.kind ?? "member-of"),
                 ...(key ? { role: "key" } : payload.role === undefined ? {} : { role: payload.role }),
+                ...(key || payload.purpose === undefined ? {} : { purpose: payload.purpose }),
                 ...(proposal.reason === null ? {} : { evidence: proposal.reason }),
                 ...decidedOrigin(decision.by),
             });
@@ -104,6 +174,23 @@ export const relationProposalsOver = (context) => {
         }),
     };
 };
+/** What a relationship update sets, checked; `null` clears a field and an absent one is left alone. */
+const changesOf = (input) => {
+    const changes = {};
+    if (input.role !== undefined)
+        changes.role = input.role === null ? null : roleOf(input.role);
+    if (input.purpose !== undefined)
+        changes.purpose = input.purpose === null ? null : purposeOf(input.purpose);
+    if (!Object.keys(changes).length)
+        throw new CliError("validation_error", "a relationship update sets a role, a purpose or both");
+    return changes;
+};
+const roleOf = (role) => {
+    const value = role.trim();
+    if (!value || value.length > 200)
+        throw new CliError("validation_error", "a role takes 1–200 characters");
+    return value;
+};
 /** A link an agent confirmed for the owner says so in its provenance. */
 const decidedOrigin = (by) => by === "owner"
     ? { origin: "owner" }

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

@@ -14757,6 +14757,22 @@ export declare const links: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}>;
+        purpose: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "links";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
     };
     dialect: 'sqlite';
     isAlias: false;

package/dist/store/sqlite/schema.js

@@ -1475,6 +1475,7 @@ export const links = sqliteTable("links", {
     createdAt: integer("created_at").notNull(),
     author: text("author"),
     updatedAt: integer("updated_at").notNull(),
+    purpose: text("purpose"),
 }, (table) => [
     index("links_unresolved").on(table.targetFolded).where(sql `to_id IS NULL`),
     index("links_by_from_type_from_id").on(table.fromType, table.fromId),

package/dist/store/sqlite/suggested-links.d.ts

@@ -0,0 +1,10 @@
+import type { CacheDatabase } from "../driver.js";
+/** Set by store version 44 and deleted once the move ran. */
+export declare const SUGGESTED_LINKS_TO_MOVE = "suggested_links_to_move";
+/**
+ * Moves the unconfirmed agent and rule links into `proposed_actions` as `relationship` and `key_document`
+ * proposals, with their bot, reason and time, so `links` holds what the owner confirmed. The moved row keeps the
+ * link's provenance under `suggestedLink`, which marks its proposer unverified: only the owner decides it. A
+ * suggestion an older build writes later stays a link, and the proposal kinds still list it.
+ */
+export declare const moveSuggestedLinks: (database: CacheDatabase, now: () => number) => number;