@wirecat/cli-core 0.558.0 → 0.560.0

package/dist/entities/mail-findings.js

@@ -0,0 +1,68 @@
+import * as v from "valibot";
+import { FACT_TYPES, MEMORY_KINDS, MEMORY_SCOPES, WORK_TASK_TYPES } from "../domain/knowledge.js";
+import { author, id, reference, text, time } from "./fields.js";
+const evidence = v.strictObject({ reference, fingerprint: text });
+const base = { id, evidence: v.array(evidence) };
+const finding = v.variant("kind", [
+    v.strictObject({
+        ...base,
+        kind: v.literal("task"),
+        project: v.optional(reference),
+        type: v.picklist(WORK_TASK_TYPES),
+        title: text,
+        reason: text,
+        commitment: v.picklist(["explicit", "inferred"]),
+        due_at: v.optional(time),
+        due_evidence: v.optional(v.array(reference)),
+        assignee: v.optional(reference),
+        assignee_evidence: v.optional(v.array(reference)),
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("fact"),
+        project: v.optional(reference),
+        subject: v.optional(reference),
+        type: v.picklist(FACT_TYPES),
+        statement: text,
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("task_update"),
+        task: reference,
+        change: v.picklist(["close", "due", "detail"]),
+        due_at: v.optional(time),
+        detail: v.optional(text),
+        reason: text,
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("memory"),
+        memory_kind: v.picklist(MEMORY_KINDS),
+        scope: v.picklist(MEMORY_SCOPES),
+        body: text,
+        subject: v.optional(reference),
+        project: v.optional(reference),
+    }),
+    v.strictObject({ ...base, kind: v.literal("link"), from: reference, to: reference, reason: text }),
+    v.strictObject({ ...base, kind: v.literal("new_contact"), address: text, name: text, reason: v.optional(text) }),
+]);
+const outcome = v.strictObject({
+    id,
+    fingerprint: text,
+    status: v.picklist(["accepted", "rejected"]),
+    reference: v.nullable(reference),
+    reused: v.boolean(),
+});
+/** A mail findings batch: what an agent read in one mailbox's new mail, waiting for the owner. */
+export const mailFindings = v.strictObject({
+    id,
+    account: v.strictObject({ provider: text, account: text }),
+    input: v.strictObject({ schema_version: v.literal(1), key: text, extractor: text, findings: v.array(finding) }),
+    fingerprint: text,
+    status: v.picklist(["proposed", "reviewed"]),
+    author,
+    decided_by: v.nullable(v.strictObject({ type: v.picklist(["person", "bot"]), id })),
+    decided_at: v.nullable(time),
+    previous: v.array(outcome),
+    receipt: v.nullable(v.strictObject({ preview_fingerprint: text, accepted: v.array(id), items: v.array(outcome) })),
+});

package/dist/entities/message-context.d.ts

@@ -222,6 +222,9 @@ export declare const messageThread: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>;
@@ -466,6 +469,9 @@ export declare const messageContext: v.UnionSchema<[v.StrictObjectSchema<{
         readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>, v.StrictObjectSchema<{
@@ -691,6 +697,9 @@ export declare const messageContext: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>;

package/dist/entities/message-write.d.ts

@@ -218,6 +218,9 @@ export declare const messageWrite: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>;
@@ -439,6 +442,9 @@ export declare const messageWrite: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>, undefined>;
@@ -668,6 +674,9 @@ export declare const messageSend: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>;
@@ -889,6 +898,9 @@ export declare const messageSend: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>, undefined>;

package/dist/entities/message.d.ts

@@ -244,6 +244,12 @@ export declare const message: v.StrictObjectSchema<{
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         /** Mail `review`: the mail rule that decided how it is stored, by its id in `rules list`; `null` when none. */
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        /** Mail `review`: the evidence fingerprint a finding cites this email by. */
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        /** Mail `review`: no earlier stored email, in any account, came from this address. */
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        /** Mail `review`: how many identities the sender's person has; 1 is this address alone. */
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>;

package/dist/entities/message.js

@@ -109,6 +109,12 @@ export const message = v.strictObject({
         list_id: v.optional(v.nullable(text)),
         /** Mail `review`: the mail rule that decided how it is stored, by its id in `rules list`; `null` when none. */
         rule_id: v.optional(v.nullable(v.number())),
+        /** Mail `review`: the evidence fingerprint a finding cites this email by. */
+        fingerprint: v.optional(v.pipe(text, v.regex(/^[a-f0-9]{64}$/))),
+        /** Mail `review`: no earlier stored email, in any account, came from this address. */
+        new_sender: v.optional(v.boolean()),
+        /** Mail `review`: how many identities the sender's person has; 1 is this address alone. */
+        sender_identities: v.optional(v.number()),
     })),
     provider_metadata: providerMetadata,
 });

package/dist/entities/store-records.d.ts

@@ -241,6 +241,9 @@ export declare const storeExport: v.UnionSchema<[v.StrictObjectSchema<{
         readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>, v.StrictObjectSchema<{

package/dist/errors/reasons.js

@@ -44,6 +44,8 @@ const OTHERS = [
     validation("meeting-findings.stale", "meeting findings changed since they were read; stage a new batch"),
     validation("meeting-findings.dedicated-review", "review meeting findings through the dedicated findings command"),
     validation("evidence-findings.stale", "evidence findings changed since they were read; stage a new batch"),
+    validation("mail-findings.stale", "mail findings cite mail that changed since it was read; stage a new batch"),
+    validation("mail-findings.partial", "a cited email is not stored whole yet; cite it once it is"),
     validation("evidence-findings.dedicated-review", "review evidence findings through the dedicated findings command"),
     validation("document.changed", "the document changed while it was read; nothing was saved"),
     ["document.not-imported", "not_found", "the document is not imported in this source account"],
@@ -151,6 +153,15 @@ const OTHERS = [
     validation("finance.ref", "the reference names no invoice or payment"),
     validation("finance.status", "the invoice's status does not allow this"),
     validation("finance.total", "the invoice's total is not the sum of its lines"),
+    validation("record.entity", "the invoice or payment the record stands for was refused"),
+    ["record.map-owner-only", "permission_error", "only the owner says which entity a source record is"],
+    validation("record.map-type", "a record maps only to an entity of its own type"),
+    validation("record.mapped", "the record already stands for another entity"),
+    validation("record.not-found", "the store holds no such record to delete"),
+    validation("record.invalid", "a field of the record is not the kind the entity needs"),
+    validation("record.reference-not-found", "a reference in the record's fields is not in the store"),
+    validation("record.relation-ambiguous", "the record names more than one target for a role that takes one"),
+    validation("record.stale-revision", "the store holds a newer revision of the record"),
     validation("memory.evidence-required", "a memory needs its evidence"),
     validation("memory.scope-required", "a memory needs its scope"),
     validation("money.amount", "the amount is not a decimal string in the currency's scale"),

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, type Kind, kindIn, k
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";
 export type { RankingComponent, RankingInput, RankingMeasure, RankingOptions, RankingTarget, RankingWeights, ScorePreset, } from "./domain/rankings-options.js";
 export { rankingOptions } from "./domain/rankings-options.js";
+export { type EnvelopeRecord, type EnvelopeSource, envelopeOfJsonl, type IngestError, RECORD_ENTITY_TYPES, RECORD_OPERATIONS, RECORDS_ENVELOPE_SCHEMA, RECORDS_SCHEMA_VERSION, type RecordEntityType, type RecordOperation, type RecordRelation, type RecordsEnvelope, } from "./domain/records.js";
 export { canonicalReference, formatReference, looksLikeReference, parseReference, REF_KINDS, type Reference, type RefKindName, type RefKindSpec, } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES, type TagType } from "./domain/tags.js";
 export { type AppErrors, DETAILS as CORE_DETAILS, failureContext, REASONS as CORE_REASONS } from "./errors/reasons.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export { CURRENCY_SCALES, currencyOf, minorUnits, moneyLabel, moneyOf, } from ".
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";
+export { envelopeOfJsonl, RECORD_ENTITY_TYPES, RECORD_OPERATIONS, RECORDS_ENVELOPE_SCHEMA, RECORDS_SCHEMA_VERSION, } from "./domain/records.js";
 export { canonicalReference, formatReference, looksLikeReference, parseReference, REF_KINDS, } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES } from "./domain/tags.js";
 export { DETAILS as CORE_DETAILS, failureContext, REASONS as CORE_REASONS } from "./errors/reasons.js";

package/dist/mail/cli/marks.d.ts

@@ -14,6 +14,7 @@ export declare const mailMark: v.StrictObjectSchema<{
         readonly envelope: v.NumberSchema<undefined>;
         readonly partial: v.NumberSchema<undefined>;
         readonly draft: v.NumberSchema<undefined>;
+        readonly suspicious: v.NumberSchema<undefined>;
     }, undefined>;
     readonly updated_at: v.StringSchema<undefined>;
 }, undefined>;

package/dist/mail/cli/marks.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
 import { outputFor } from "../../cli/context.js";
-import { destroysNothing, LOCAL_WRITE } from "../../cli/effects.js";
+import { LOCAL_WRITE, proposesOnly } from "../../cli/effects.js";
 import { itemOf, renderAnswer } from "../../cli/envelope.js";
 import { acknowledgeMark } from "../marks.js";
 const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
@@ -14,7 +14,13 @@ export const mailMark = v.strictObject({
     through_received_at: v.nullable(v.string()),
     held: v.number(),
     read: v.number(),
-    skipped: v.strictObject({ bulk: v.number(), envelope: v.number(), partial: v.number(), draft: v.number() }),
+    skipped: v.strictObject({
+        bulk: v.number(),
+        envelope: v.number(),
+        partial: v.number(),
+        draft: v.number(),
+        suspicious: v.number(),
+    }),
     updated_at: v.string(),
 });
 export const markItem = (mark) => ({
@@ -28,12 +34,13 @@ export const markItem = (mark) => ({
 });
 export const markText = (mark) => `${mark.holder}  through ${mark.throughId}${mark.throughAt === null ? "" : ` (${iso(mark.throughAt)})`}  ` +
     `read ${mark.read}  held ${mark.held.length}  skipped bulk ${mark.skipped.bulk}, envelope ${mark.skipped.envelope}, ` +
-    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}  updated ${iso(mark.updatedAt)}\n`;
+    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}, suspicious ${mark.skipped.suspicious}  ` +
+    `updated ${iso(mark.updatedAt)}\n`;
 /**
  * `messages acknowledge`: a holder says it is done with what `review --holder` gave it, and its mark moves there. It
  * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it.
  */
-export const acknowledgeCommand = (mail) => answerEntity(destroysNothing(annotate(new Command("acknowledge"), {
+export const acknowledgeCommand = (mail) => answerEntity(proposesOnly(annotate(new Command("acknowledge"), {
     effects: LOCAL_WRITE,
     examples: [
         `${mail.app.command} personal messages acknowledge --holder mail-triage --cursor 9123.1762090000000`,

package/dist/mail/cli/review.js

@@ -114,6 +114,13 @@ const reviewAnswer = (found, mailbox, fresh) => {
                 bulk: message.marks?.bulk ?? false,
                 list_id: message.marks?.listId ?? null,
                 rule_id: message.marks?.ruleId ?? null,
+                ...(message.marks
+                    ? {
+                        fingerprint: message.marks.fingerprint,
+                        new_sender: message.marks.newSender,
+                        sender_identities: message.marks.senderIdentities,
+                    }
+                    : {}),
             },
         })),
         limit: Math.max(1, read.length),
@@ -202,11 +209,12 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
     .option("--unanswered [duration]", "only threads whose newest email came to you, in To or Cc, with no answer for this long — 4h, 1d; 24h if not given")
     .option("--waiting [duration]", "only threads where you wrote last and nobody answered for this long — 3d; 7d if not given")
     .option("--holder <name>", "read for this holder — an agent or a pipeline — what is stored past its processing mark, by store order; " +
-    "bulk, envelopes, drafts and partial mail left out; `messages acknowledge` moves the mark")
+    "bulk, envelopes, drafts, suspicious senders and partial mail left out; `messages acknowledge` moves the mark")
     .option("--new", "what changed since the last `review --new` of this mailbox, a point per thread — for scheduled runs")
     .addHelpText("after", `
 Without a date, --unanswered and --waiting look at threads active in the last ${OWED_DAYS} days.
-Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score.
+Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score,
+the fingerprint a finding cites it by, new_sender (no earlier email from the address) and sender_identities.
 bulk:false leaves out threads whose newest email is mail sent to many, a list's or recorded by an envelope rule.
 Mail newer than the last finished sync waits for the next review. Each reader keeps its own --new point: you,
 an agent over MCP, and each scheduled run.`)

package/dist/mail/findings.d.ts

@@ -0,0 +1,55 @@
+import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
+import { type FactFinding, type FindingEvidence, type TaskFinding } from "../meetings/index.js";
+export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
+/** At most this many findings in one run's batch, and per sender in it. */
+export declare const MAIL_FINDINGS_PER_RUN = 30;
+export declare const MAIL_FINDINGS_PER_SENDER = 5;
+interface Cited {
+    id: string;
+    evidence: FindingEvidence[];
+}
+export type MailTaskFinding = TaskFinding;
+export type MailFactFinding = FactFinding;
+export interface MailTaskUpdateFinding extends Cited {
+    kind: "task_update";
+    task: string;
+    change: "close" | "due" | "detail";
+    dueAt?: string;
+    detail?: string;
+    reason: string;
+}
+export interface MailMemoryFinding extends Cited {
+    kind: "memory";
+    memoryKind: (typeof MEMORY_KINDS)[number];
+    scope: (typeof MEMORY_SCOPES)[number];
+    body: string;
+    subject?: string;
+    project?: string;
+}
+/** Address → person, person → organization, or thread → project. */
+export interface MailLinkFinding extends Cited {
+    kind: "link";
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface MailNewContactFinding extends Cited {
+    kind: "new_contact";
+    address: string;
+    name: string;
+    reason?: string;
+}
+export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding;
+export interface MailFindingsInput {
+    schemaVersion: 1;
+    /** `<holder>:<through_id>`: one batch per run of a holder over the mail it was given. */
+    key: string;
+    extractor: string;
+    findings: MailFinding[];
+}
+/**
+ * The shape of a mail findings batch: 1–30 findings, each citing 1–8 `msg:email/…` references with fingerprints.
+ * What needs the store — the fingerprints, partial mail, the per-sender cap, the targets — the store checks.
+ */
+export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
+export declare const mailFindingFingerprint: ({ id: _id, ...finding }: MailFinding) => string;

package/dist/mail/findings.js

@@ -0,0 +1,140 @@
+import { CliError } from "@wirecat/cli-base";
+import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
+import { formatLocator, parseLocator } from "../domain/locator.js";
+import { parseReference } from "../domain/references.js";
+import { findingFields, findingHash, findingId, findingText, meetingTimestamp, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
+export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
+/** At most this many findings in one run's batch, and per sender in it. */
+export const MAIL_FINDINGS_PER_RUN = 30;
+export const MAIL_FINDINGS_PER_SENDER = 5;
+const invalid = (message) => {
+    throw new CliError("validation_error", message);
+};
+const emailEvidence = (raw) => {
+    try {
+        const locator = parseLocator(raw);
+        if (locator.provider === "email")
+            return formatLocator(locator);
+    }
+    catch { }
+    return invalid("mail finding evidence is a msg:email/… reference");
+};
+const RULES = {
+    plural: "mail findings",
+    singular: "mail finding",
+    cited: "reference",
+    reference: emailEvidence,
+    anySubject: true,
+    inboxTasks: true,
+};
+const typeOf = (reference) => {
+    try {
+        const parsed = parseReference(reference);
+        return parsed.type === "contact" || parsed.type === "chat" ? `${parsed.type}:${parsed.provider}` : parsed.type;
+    }
+    catch {
+        return undefined;
+    }
+};
+const LINKS = {
+    "contact:email": "person",
+    person: "organization",
+    "chat:email": "project",
+};
+const ADDRESS = /^[^\s@<>]+@[^\s@<>]+$/;
+const one = (raw, ids) => {
+    if (!raw || typeof raw !== "object")
+        return invalid("a finding is an object");
+    if (raw.kind === "task" || raw.kind === "fact")
+        return validateFinding(raw, RULES, ids);
+    const id = findingId(raw.id, ids);
+    const evidence = validEvidence(raw.evidence, RULES);
+    const reference = (value, pattern, what) => {
+        const text = findingText(value, 400);
+        if (!pattern.test(text))
+            return invalid(`${what} is not a reference of the kind it takes: ${text}`);
+        return text;
+    };
+    switch (raw.kind) {
+        case "task_update": {
+            findingFields(raw, ["id", "kind", "task", "change", "dueAt", "detail", "reason", "evidence"], RULES.singular);
+            const task = reference(raw.task, /^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/, "a task update's task");
+            const change = raw.change;
+            if (change !== "close" && change !== "due" && change !== "detail")
+                return invalid("a task update's change is close, due or detail");
+            if ((change === "due") !== (raw.dueAt !== undefined))
+                return invalid("a due change, and only it, gives due_at");
+            if ((change === "detail") !== (raw.detail !== undefined))
+                return invalid("a detail change, and only it, gives detail");
+            return {
+                id,
+                kind: "task_update",
+                task,
+                change,
+                ...(raw.dueAt === undefined
+                    ? {}
+                    : { dueAt: meetingTimestamp(raw.dueAt, "a task update's due date") }),
+                ...(raw.detail === undefined ? {} : { detail: findingText(raw.detail, 2000) }),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
+        case "memory": {
+            findingFields(raw, ["id", "kind", "memoryKind", "scope", "body", "subject", "project", "evidence"], RULES.singular);
+            if (!MEMORY_KINDS.includes(raw.memoryKind))
+                return invalid(`a memory's memory_kind is ${MEMORY_KINDS.join(", ")}`);
+            if (!MEMORY_SCOPES.includes(raw.scope))
+                return invalid("a memory's scope is personal or work");
+            if (raw.subject === undefined && raw.project === undefined)
+                return invalid("a memory is about a subject or a project");
+            return {
+                id,
+                kind: "memory",
+                memoryKind: raw.memoryKind,
+                scope: raw.scope,
+                body: findingText(raw.body, 20_000),
+                ...(raw.subject === undefined
+                    ? {}
+                    : { subject: reference(raw.subject, /^(person|organization|project):[1-9]\d*$/, "a memory's subject") }),
+                ...(raw.project === undefined ? {} : { project: reference(raw.project, /^project:[1-9]\d*$/, "a project") }),
+                evidence,
+            };
+        }
+        case "link": {
+            findingFields(raw, ["id", "kind", "from", "to", "reason", "evidence"], RULES.singular);
+            const from = findingText(raw.from, 400);
+            const to = findingText(raw.to, 80);
+            const wanted = LINKS[typeOf(from) ?? ""];
+            if (!wanted || typeOf(to) !== wanted || !/:[1-9]\d*$/.test(to))
+                return invalid("a link goes from contact:email/<address> to person:, person: to organization:, or chat:email/… to project:");
+            return { id, kind: "link", from, to, reason: findingText(raw.reason, 2000), evidence };
+        }
+        case "new_contact": {
+            findingFields(raw, ["id", "kind", "address", "name", "reason", "evidence"], RULES.singular);
+            const address = findingText(raw.address, 320).toLowerCase();
+            if (!ADDRESS.test(address))
+                return invalid("a new contact's address is an email address");
+            return {
+                id,
+                kind: "new_contact",
+                address,
+                name: findingText(raw.name, 200),
+                ...(raw.reason === undefined ? {} : { reason: findingText(raw.reason, 2000) }),
+                evidence,
+            };
+        }
+        default:
+            return invalid("a mail finding is a task, task_update, fact, memory, link or new_contact");
+    }
+};
+/**
+ * The shape of a mail findings batch: 1–30 findings, each citing 1–8 `msg:email/…` references with fingerprints.
+ * What needs the store — the fingerprints, partial mail, the per-sender cap, the targets — the store checks.
+ */
+export const validateMailFindings = (input) => {
+    const batch = validateBatch(input, RULES, MAIL_FINDINGS_PER_RUN, one);
+    if (!/^[a-z0-9][a-z0-9-]{0,39}:[1-9]\d*$/.test(batch.key))
+        return invalid("a mail findings key is <holder>:<through_id>, such as mail-triage:9123456");
+    return batch;
+};
+export const mailFindingFingerprint = ({ id: _id, ...finding }) => findingHash(finding);

package/dist/mail/index.d.ts

@@ -1,12 +1,13 @@
 export { mailAccountKey } from "./account-key.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
+export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
-export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, holderHasMail, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
 export { type MailTurn, mailTurn } from "./owed.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PARTIAL, type PartialOutcome } from "./partial.js";

package/dist/mail/index.js

@@ -1,12 +1,13 @@
 export { mailAccountKey } from "./account-key.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
+export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
-export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, holderHasMail, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
 export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";

package/dist/mail/marks.d.ts

@@ -5,7 +5,7 @@ export declare const HOLDER: RegExp;
 export declare const MARK_BATCH = 200;
 /** A partial email waits this long to be stored whole, then is skipped. */
 export declare const HOLD_PARTIAL_MS: number;
-export type SkipReason = "bulk" | "envelope" | "partial" | "draft";
+export type SkipReason = "bulk" | "envelope" | "partial" | "draft" | "suspicious";
 /**
  * How far one holder — an agent, a pipeline — has processed an account's mail, in the shared store (`sync_cursors`,
  * key `consumer:<holder>`). It counts by the store's insert order (`emails.id`), so mail stored late, older than what
@@ -28,7 +28,7 @@ export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Prom
 /** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
 export declare const cursorOf: (throughId: number, readAt: number) => string;
 export interface MarkRead {
-    /** The emails for the holder, oldest first; bulk, envelopes, drafts and partial mail left out. */
+    /** The emails for the holder, oldest first; bulk, envelopes, drafts, suspicious senders and partial mail left out. */
     emails: StoredHit[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
@@ -44,10 +44,17 @@ export interface MarkRead {
  * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
  * empty and gives the cursor of the newest stored email.
  */
-export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, { now, limit }?: {
+export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, options?: {
     now?: number;
     limit?: number;
 }) => Promise<MarkRead>;
+/**
+ * Whether the holder has mail to read in any stored mailbox — what a schedule asks before it starts the holder's
+ * agent, so a run with nothing new costs no model call. Mail that is only skipped (bulk, envelopes, drafts,
+ * suspicious senders) moves the holder's mark here, as the agent would have acknowledged it, or it would wait
+ * forever behind the mark. A holder with no mark yet has mail to read: its first run sets the mark.
+ */
+export declare const holderHasMail: (store: MessageStore, holder: string, now?: number) => Promise<boolean>;
 /**
  * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
  * still partial, or changed after the read (it may have become whole since), is held and comes with the next read.