@wirecat/cli-core 0.362.0 → 0.363.0

package/dist/store/evidence-findings.d.ts

@@ -0,0 +1,63 @@
+import { type FindingOutcome, type FindingsInput, type FindingsReceipt } from "../meetings/index.js";
+export declare const EVIDENCE_FINDINGS_KIND = "evidence_findings";
+export declare const validateEvidenceFindings: (input: FindingsInput) => FindingsInput;
+/** Who decided: the owner, or an agent the host let decide for the owner, with its reason. */
+export type EvidenceFindingsDecider = "owner" | {
+    bot: string;
+    model?: string;
+    reason: string;
+};
+export interface EvidenceFindingsReceipt extends FindingsReceipt {
+    decision: {
+        by: "owner";
+    } | {
+        by: "agent";
+        bot: string;
+        model: string | null;
+        reason: string;
+    };
+}
+export interface EvidenceFindingsBatch {
+    id: string;
+    project: string;
+    input: FindingsInput;
+    fingerprint: string;
+    status: "proposed" | "reviewed";
+    author: {
+        type: "person" | "bot";
+        id: string;
+        name: string | null;
+    };
+    decidedBy: {
+        type: "person" | "bot";
+        id: string;
+    } | null;
+    decidedAt: string | null;
+    previous: FindingOutcome[];
+    receipt: EvidenceFindingsReceipt | null;
+}
+/**
+ * Cited facts and follow-ups about one project from stored messages, mail and documents, staged by an agent for
+ * review. A sibling of meeting findings: the same rules, evidence checked against the current stored text.
+ */
+export interface EvidenceFindingsStore {
+    stage(input: FindingsInput, agent: {
+        bot: string;
+        model?: string;
+    }): Promise<EvidenceFindingsBatch>;
+    get(id: string): Promise<EvidenceFindingsBatch>;
+    list(options?: {
+        project?: string;
+        limit?: number;
+        offset?: number;
+        status?: "proposed" | "reviewed";
+    }): Promise<{
+        items: EvidenceFindingsBatch[];
+        hasMore: boolean;
+    }>;
+    review(id: string, input: {
+        fingerprint: string;
+        accept: string[];
+        by?: EvidenceFindingsDecider;
+    }): Promise<EvidenceFindingsBatch>;
+}

package/dist/store/evidence-findings.js

@@ -0,0 +1,15 @@
+import { CliError } from "@wirecat/cli-base";
+import { formatLocator, parseLocator } from "../domain/locator.js";
+import { validateFindings } from "../meetings/index.js";
+export const EVIDENCE_FINDINGS_KIND = "evidence_findings";
+const reference = (raw) => {
+    if (/^document:[1-9]\d*$/.test(raw))
+        return raw;
+    try {
+        return formatLocator(parseLocator(raw));
+    }
+    catch {
+        throw new CliError("validation_error", "finding evidence is a msg: or document: reference");
+    }
+};
+export const validateEvidenceFindings = (input) => validateFindings(input, { plural: "evidence findings", singular: "evidence finding", cited: "reference", reference });

package/dist/store/index.d.ts

@@ -9,6 +9,7 @@ export type { DocumentTransferOptions, DocumentTransferPreview, DocumentTransfer
 export { applyDocumentTransfer, previewDocumentTransfer } from "./document-transfer/index.js";
 export type { CacheDatabase, CacheStatement, OpenDatabase, SqlValue } from "./driver.js";
 export { PRAGMAS } from "./driver.js";
+export { EVIDENCE_FINDINGS_KIND, type EvidenceFindingsBatch, type EvidenceFindingsDecider, type EvidenceFindingsReceipt, type EvidenceFindingsStore, validateEvidenceFindings, } from "./evidence-findings.js";
 export type { MeetingFindingsBatch, MeetingFindingsStore } from "./meeting-findings.js";
 export { MIGRATIONS, type Migration, migrate } from "./migrations.js";
 export { openCache } from "./open.js";

package/dist/store/index.js

@@ -2,6 +2,7 @@ export { FACT_STATUSES, FACT_TYPES, MEMORY_KINDS, MEMORY_SCOPES, MEMORY_STATUSES
 export { createTagRedirectIndex } from "../domain/tag-redirects.js";
 export { applyDocumentTransfer, previewDocumentTransfer } from "./document-transfer/index.js";
 export { PRAGMAS } from "./driver.js";
+export { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "./evidence-findings.js";
 export { MIGRATIONS, migrate } from "./migrations.js";
 export { openCache } from "./open.js";
 export { storePath } from "./path.js";

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

@@ -1,7 +1,15 @@
-import { type ContextEvidenceReader, type ContextIndex } from "../../context/evidence.js";
+import { type ContextEvidenceReader, type ContextIndex, type ContextRecordReader } from "../../context/evidence.js";
 import type { Stemmer, Stemmers } from "../../search/stem.js";
 import type { StoreContext } from "./open.js";
 /** No index fills, model loads or record hydration outside the read transaction. */
 export declare const contextEvidenceOver: ({ database }: Pick<StoreContext, "database">) => ContextEvidenceReader;
 /** The same fills a mail search and the notes search run before reading; a message is indexed when it is saved. */
 export declare const contextIndexOver: ({ database }: Pick<StoreContext, "database">, stemmerFor: (stemmers: Stemmers) => Stemmer) => ContextIndex;
+/** The cited record by reference, read with the context reader's own columns, so fingerprints agree. */
+export declare const contextRecordOf: (database: StoreContext["database"], ref: string) => {
+    ref: string;
+    title: string | null;
+    text: string;
+    revision: number | null;
+} | null;
+export declare const contextRecordsOver: ({ database }: Pick<StoreContext, "database">) => ContextRecordReader;

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

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { contextCursorScope, contextEvidenceRequest, } from "../../context/evidence.js";
-import { formatLocator } from "../../domain/locator.js";
+import { formatLocator, parseLocator } from "../../domain/locator.js";
 import { NORMALIZER_VERSION, normalize } from "../normalize.js";
 import { contextDocumentTime, contextDocumentTimeKind, contextDocumentUrl } from "./context-document-source.js";
 import { readMeetingContextEvidence } from "./context-meeting-source.js";
@@ -178,3 +178,45 @@ export const contextIndexOver = ({ database }, stemmerFor) => ({
         return { mail, documents };
     },
 });
+/** The cited record by reference, read with the context reader's own columns, so fingerprints agree. */
+export const contextRecordOf = (database, ref) => {
+    if (typeof ref !== "string")
+        return null;
+    const document = /^document:([1-9]\d*)$/.exec(ref);
+    if (document) {
+        const corpus = corpora.document;
+        const row = database
+            .prepare(`SELECT ${corpus.title} AS title,${corpus.body} AS body,${corpus.revision} AS revision FROM documents n
+         WHERE n.id=? AND n.deleted_at IS NULL AND ${corpus.where}`)
+            .get(Number(document[1]));
+        return row
+            ? {
+                ref,
+                title: row.title == null ? null : String(row.title),
+                text: String(row.body),
+                revision: row.revision == null ? null : Number(row.revision),
+            }
+            : null;
+    }
+    let at;
+    try {
+        at = parseLocator(ref);
+    }
+    catch {
+        return null;
+    }
+    const corpus = at.provider === "email" ? corpora.mail : corpora.message;
+    const row = database
+        .prepare(`SELECT ${corpus.title} AS title,${corpus.body} AS body FROM ${corpus.table} n JOIN accounts a ON a.id=n.account_id
+       ${corpus.join} WHERE a.provider=? AND a.external_id=? AND c.external_id=? AND n.external_id=?
+       AND n.deleted_at IS NULL AND ${corpus.where}`)
+        .get(at.provider, at.account, at.chat, at.message);
+    return row
+        ? { ref, title: row.title == null ? null : String(row.title), text: String(row.body), revision: null }
+        : null;
+};
+export const contextRecordsOver = ({ database }) => ({
+    async read(ref) {
+        return read(database, () => contextRecordOf(database, ref));
+    },
+});

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

@@ -0,0 +1,3 @@
+import { type EvidenceFindingsStore } from "../evidence-findings.js";
+import type { StoreContext } from "./open.js";
+export declare const evidenceFindingsStoreOver: (context: StoreContext) => EvidenceFindingsStore;

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

@@ -0,0 +1,172 @@
+import { CliError } from "@wirecat/cli-base";
+import { contextEvidenceFingerprint } from "../../context/evidence.js";
+import { findingFingerprint, findingHash } from "../../meetings/index.js";
+import { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "../evidence-findings.js";
+import { contextRecordOf } from "./context-evidence.js";
+import { findingsAgent, findingsCoreOver } from "./findings-core.js";
+import { authorActor } from "./memories.js";
+import { proposalOperationsOver } from "./proposed-actions.js";
+import { write } from "./transaction.js";
+const stale = () => {
+    throw new CliError("validation_error", "evidence findings changed since they were read; stage a new batch", {
+        reason: "evidence-findings.stale",
+    });
+};
+const invalid = (message) => {
+    throw new CliError("validation_error", message);
+};
+const TEXT_BUDGET = 262144;
+export const evidenceFindingsStoreOver = (context) => {
+    const { database } = context;
+    const proposals = proposalOperationsOver(context);
+    const core = findingsCoreOver(context, EVIDENCE_FINDINGS_KIND);
+    const load = (id) => {
+        if (typeof id !== "string" || !/^[1-9]\d*$/.test(id) || !Number.isSafeInteger(Number(id)))
+            return invalid("a findings batch needs a stored ID");
+        const row = database
+            .prepare("SELECT length(CAST(payload AS BLOB)) AS bytes,length(CAST(result AS BLOB)) AS result_bytes FROM proposed_actions WHERE id=? AND account_id IS NULL AND kind=?")
+            .get(Number(id), EVIDENCE_FINDINGS_KIND);
+        if (!row)
+            throw new CliError("not_found", "the evidence findings batch is unavailable");
+        if (Number(row.bytes) > 100000 || Number(row.result_bytes) > 65536)
+            return invalid("stored findings exceed the read budget");
+        return proposals.get(id);
+    };
+    const view = (proposal) => {
+        const input = proposal.payload;
+        if (!input || !proposal.target || !["proposed", "approved"].includes(proposal.status))
+            return invalid("invalid stored findings batch");
+        return {
+            id: proposal.id,
+            project: proposal.target,
+            input: { schemaVersion: 1, key: input.key, extractor: input.extractor, findings: input.findings },
+            fingerprint: findingHash({ input, author: proposal.proposedBy.id }),
+            status: proposal.status === "proposed" ? "proposed" : "reviewed",
+            author: proposal.proposedBy,
+            decidedBy: proposal.decidedBy,
+            decidedAt: proposal.decidedAt,
+            previous: proposal.result
+                ? proposal.result.items
+                : input.findings.flatMap((finding) => {
+                    const held = core.previous(null, findingFingerprint(finding));
+                    return held ? [{ ...held, id: finding.id, reused: true }] : [];
+                }),
+            receipt: proposal.result,
+        };
+    };
+    const snapshot = (input) => {
+        let readBytes = 0;
+        return core.snapshot(input, (evidence, _finding, _project, seen) => {
+            if (seen.has(evidence.reference)) {
+                if (seen.get(evidence.reference) !== evidence.fingerprint)
+                    return stale();
+                return;
+            }
+            const record = contextRecordOf(database, evidence.reference);
+            if (!record)
+                return stale();
+            readBytes += Buffer.byteLength(record.text) + Buffer.byteLength(record.title ?? "");
+            if (readBytes > TEXT_BUDGET)
+                return invalid(`finding evidence exceeds the ${TEXT_BUDGET}-byte stored text budget`);
+            const fingerprint = contextEvidenceFingerprint(record);
+            if (fingerprint !== evidence.fingerprint)
+                return stale();
+            seen.set(evidence.reference, fingerprint);
+        });
+    };
+    const decider = (by) => {
+        if (by === undefined || by === "owner")
+            return { author: "owner", decision: { by: "owner" } };
+        const raw = by;
+        const agent = findingsAgent({
+            bot: raw.bot,
+            ...(raw.model === undefined ? {} : { model: raw.model }),
+        });
+        if (typeof raw.reason !== "string" || !raw.reason.trim() || raw.reason.length > 2000)
+            return invalid("an agent deciding for the owner gives a reason of 1–2000 characters");
+        return {
+            author: agent,
+            decision: { by: "agent", bot: agent.bot, model: agent.model ?? null, reason: raw.reason.trim() },
+        };
+    };
+    return {
+        stage: async (raw, rawAgent) => {
+            const input = validateEvidenceFindings(raw);
+            const projects = new Set(input.findings.map((finding) => finding.project));
+            if (projects.size !== 1)
+                return invalid("an evidence findings batch is about one project");
+            const by = findingsAgent(rawAgent);
+            return write(database, () => {
+                const { actor } = authorActor(context, by);
+                const inputHash = findingHash({ input, model: by.model ?? null });
+                const held = database
+                    .prepare("SELECT id FROM proposed_actions WHERE account_id IS NULL AND kind=? AND proposed_by_type=? AND proposed_by_id=? AND json_extract(payload,'$.key')=? ORDER BY id LIMIT 1")
+                    .get(EVIDENCE_FINDINGS_KIND, actor.type, actor.id, input.key);
+                if (held) {
+                    const proposal = load(String(held.id));
+                    if (proposal.payload.inputHash !== inputHash)
+                        return invalid("the findings batch key was already used for different input");
+                    return view(proposal);
+                }
+                const snapshotHash = snapshot(input);
+                const fingerprints = input.findings.map(findingFingerprint);
+                if (new Set(fingerprints).size !== fingerprints.length)
+                    return invalid("the batch contains duplicate findings");
+                return view(proposals.propose({
+                    kind: EVIDENCE_FINDINGS_KIND,
+                    by,
+                    target: [...projects][0],
+                    payload: { ...input, inputHash, snapshotHash, agentModel: by.model ?? null },
+                }));
+            });
+        },
+        get: async (id) => view(load(id)),
+        list: async ({ project, limit = 20, offset = 0, status } = {}) => {
+            if (status !== undefined && status !== "proposed" && status !== "reviewed")
+                return invalid("finding status is proposed or reviewed");
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50 || !Number.isSafeInteger(offset) || offset < 0)
+                return invalid("findings lists take 1–50 items and a nonnegative offset");
+            const projectId = project === undefined ? null : /^project:([1-9]\d*)$/.exec(project)?.[1];
+            if (projectId === undefined)
+                return invalid("a findings list filters by a project reference");
+            const ids = database
+                .prepare("SELECT id FROM proposed_actions WHERE account_id IS NULL AND kind=? AND (? IS NULL OR (target_type='project' AND target_id=?)) AND (? IS NULL OR status=?) ORDER BY id DESC LIMIT ? OFFSET ?")
+                .all(EVIDENCE_FINDINGS_KIND, projectId, projectId === null ? null : Number(projectId), status ?? null, status === "reviewed" ? "approved" : (status ?? null), limit + 1, offset);
+            return { items: ids.slice(0, limit).map((row) => view(load(String(row.id)))), hasMore: ids.length > limit };
+        },
+        review: async (id, decision) => write(database, () => {
+            const proposal = load(id);
+            const batch = view(proposal);
+            if (!decision || typeof decision.fingerprint !== "string" || decision.fingerprint !== batch.fingerprint)
+                return stale();
+            if (!Array.isArray(decision.accept) ||
+                decision.accept.length > 16 ||
+                new Set(decision.accept).size !== decision.accept.length ||
+                decision.accept.some((candidate) => !batch.input.findings.some((finding) => finding.id === candidate)))
+                return invalid("accept only unique IDs shown in this batch");
+            const accepted = [...decision.accept].sort();
+            const { author, decision: decidedBy } = decider(decision.by);
+            if (batch.receipt) {
+                if (JSON.stringify(batch.receipt.accepted) !== JSON.stringify(accepted))
+                    return invalid("this findings batch was already reviewed with a different decision");
+                return batch;
+            }
+            const input = proposal.payload;
+            if (snapshot(batch.input) !== input.snapshotHash)
+                return stale();
+            if (proposal.proposedBy.type !== "bot" || !proposal.proposedBy.name)
+                return invalid("a findings author must be an agent");
+            const agent = {
+                bot: proposal.proposedBy.name,
+                ...(input.agentModel === null ? {} : { model: input.agentModel }),
+            };
+            const items = core.outcomes(null, batch.input, accepted, agent);
+            return view(proposals.approve(id, {
+                previewFingerprint: batch.fingerprint,
+                accepted,
+                items,
+                decision: decidedBy,
+            }, author));
+        }),
+    };
+};

package/dist/store/sqlite/findings-core.d.ts

@@ -0,0 +1,17 @@
+import { type Finding, type FindingEvidence, type FindingOutcome, type FindingsInput } from "../../meetings/index.js";
+import type { StoreContext } from "./open.js";
+export interface FindingsAgent {
+    bot: string;
+    model?: string;
+}
+export declare const findingsAgent: (agent: FindingsAgent) => FindingsAgent;
+/**
+ * What meeting and evidence findings share: the project and assignee snapshot, earlier decisions on an unchanged
+ * candidate, creating the accepted facts and tasks, and the receipt items. Each kind checks its own evidence,
+ * including a reference it already saw for another finding.
+ */
+export declare const findingsCoreOver: (context: StoreContext, kind: string) => {
+    snapshot: (input: FindingsInput, cite: (evidence: FindingEvidence, finding: Finding, projectId: string, seen: Map<string, unknown>) => void) => string;
+    previous: (account: number | null, fingerprint: string) => FindingOutcome | undefined;
+    outcomes: (account: number | null, input: FindingsInput, accepted: string[], agent: FindingsAgent) => FindingOutcome[];
+};

package/dist/store/sqlite/findings-core.js

@@ -0,0 +1,108 @@
+import { CliError } from "@wirecat/cli-base";
+import { findingFingerprint, findingHash, } from "../../meetings/index.js";
+import { factOperationsOver } from "./facts.js";
+import { linkEvidence } from "./memories.js";
+import { requiredThing } from "./notes.js";
+import { taskRowOf } from "./things.js";
+import { workTaskOperationsOver } from "./work-tasks.js";
+const invalid = (message) => {
+    throw new CliError("validation_error", message);
+};
+export const findingsAgent = (agent) => {
+    if (!agent ||
+        typeof agent.bot !== "string" ||
+        !agent.bot.trim() ||
+        agent.bot.length > 200 ||
+        agent.bot === "owner" ||
+        (agent.model !== undefined && (typeof agent.model !== "string" || agent.model.length > 200)))
+        return invalid("findings must name an agent author independently of their payload");
+    return { bot: agent.bot, ...(agent.model === undefined ? {} : { model: agent.model }) };
+};
+/**
+ * What meeting and evidence findings share: the project and assignee snapshot, earlier decisions on an unchanged
+ * candidate, creating the accepted facts and tasks, and the receipt items. Each kind checks its own evidence,
+ * including a reference it already saw for another finding.
+ */
+export const findingsCoreOver = (context, kind) => {
+    const { database } = context;
+    const facts = factOperationsOver(context);
+    const tasks = workTaskOperationsOver(context);
+    const snapshot = (input, cite) => {
+        const seen = new Map();
+        for (const finding of input.findings) {
+            const project = requiredThing(database, finding.project, "the project");
+            if (project.type !== "project")
+                return invalid("a finding needs an owner project");
+            const projectRow = database
+                .prepare("SELECT id,key,name,description,type,scope,updated_at FROM projects WHERE id=? AND account_id IS NULL AND deleted_at IS NULL")
+                .get(project.id);
+            if (!projectRow)
+                throw new CliError("not_found", "the owner project is unavailable");
+            seen.set(finding.project, projectRow);
+            if (finding.kind === "task" && finding.assignee) {
+                const person = requiredThing(database, finding.assignee, "the assignee");
+                if (person.type !== "person")
+                    return invalid("the assignee must be a stored person");
+                const personRow = database.prepare("SELECT id,name,updated_at FROM persons WHERE id=?").get(person.id);
+                if (!personRow)
+                    throw new CliError("not_found", "the assignee is unavailable");
+                seen.set(finding.assignee, personRow);
+            }
+            for (const evidence of finding.evidence)
+                cite(evidence, finding, String(project.id), seen);
+        }
+        return findingHash([...seen].sort(([a], [b]) => a.localeCompare(b)));
+    };
+    const previous = (account, fingerprint) => {
+        const row = database
+            .prepare("SELECT substr(j.value,1,4096) AS item FROM proposed_actions p,json_each(p.result,'$.items') j WHERE p.account_id IS ? AND p.kind=? AND p.status='approved' AND json_extract(j.value,'$.fingerprint')=? ORDER BY p.id LIMIT 1")
+            .get(account, kind, fingerprint);
+        return row ? JSON.parse(String(row.item)) : undefined;
+    };
+    const create = (finding, agent) => {
+        const evidence = finding.evidence.map((item) => item.reference);
+        if (finding.kind === "fact") {
+            const fact = facts.add({
+                type: finding.type,
+                statement: finding.statement,
+                project: finding.project,
+                evidence,
+                by: agent,
+            });
+            return facts.accept(fact.ref).ref;
+        }
+        const task = tasks.create({
+            project: finding.project,
+            title: finding.title,
+            type: finding.type,
+            description: `${finding.commitment}: ${finding.reason}`,
+            ...(finding.dueAt ? { dueAt: new Date(finding.dueAt) } : {}),
+        }, agent);
+        const id = taskRowOf(database, task.id);
+        if (id === undefined)
+            throw new CliError("configuration_error", "created finding task is unavailable");
+        linkEvidence(context, { type: finding.type, id }, evidence, "agent");
+        if (finding.assignee)
+            tasks.assign(task.id, { to: finding.assignee, role: "assignee" }, agent);
+        return task.ref;
+    };
+    /** Reuses an earlier decision on an unchanged candidate; refuses to accept one that was rejected. */
+    const outcomes = (account, input, accepted, agent) => input.findings.map((finding) => {
+        const fingerprint = findingFingerprint(finding);
+        const prior = previous(account, fingerprint);
+        if (prior) {
+            if (accepted.includes(finding.id) && prior.status === "rejected")
+                return invalid("this unchanged finding was already rejected; changed evidence needs a new candidate");
+            return { ...prior, id: finding.id, reused: true };
+        }
+        const status = accepted.includes(finding.id) ? "accepted" : "rejected";
+        return {
+            id: finding.id,
+            fingerprint,
+            status,
+            reference: status === "accepted" ? create(finding, agent) : null,
+            reused: false,
+        };
+    });
+    return { snapshot, previous, outcomes };
+};