@wirecat/cli-core 0.579.0 → 0.581.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ shape of this file.
 
 ## Unreleased
 
+## 0.581.0 — 05.11.2026
+
+### Added
+
+- **`review --holder` gives the findings key.** A host that mounts its findings command (`MailMount.findings`)
+  gets a `mail-findings.add` step with `key` before the acknowledge step, so an agent copies the key instead of
+  building it from the cursor. The text answer names it too.
+
+### Fixed
+
+- **A run after `messages reset` can stage its findings.** The reset counts on the mark (`resets`), and the findings
+  key of a mark moved back is `<holder>:<through_id>-r<resets>`, such as `mail-triage:277352-r1`. The runs after a
+  reset reached the through id of a batch staged before it and were refused (`mail-findings.key-used`), so their
+  mark stayed. Keys of marks never moved back keep their shape, and the same review still gives the same key, so
+  a retry of one run stages nothing twice.
+
+## 0.580.0 — 05.11.2026
+
+### Added
+
+- **`mailFindings.check` tries a whole mail findings batch without staging it.** It makes every check `stage`
+  makes, the trial write of each invoice, payment and order included, rolls everything back and answers
+  `{ valid, findings, batch, problems }`: one problem per finding that would be refused, with its id, kind, code,
+  message and details, and the batch's own problems (`mail-findings.key-used` when the key holds other input). Its
+  input is `readMailFindingsJson`, the decoded JSON before validation.
+- **Mail findings name a party the store does not hold yet.** An invoice takes `counterparty_name`, a payment
+  `payer_name` and `payee_name`, an order `customer_name`, each with an optional `<party>_email` that sent or
+  received a cited email. The owner's accept finds the organization by that address, by its company domain or by
+  exact name, or makes a company of that name and joins the address to it; two matches are refused
+  (`finance.party`).
+
+### Fixed
+
+- **An unknown finding field is named.** The refusal says the field, the finding's id and kind and what that kind
+  takes, also in `details` (`fields`, `allowed`, `finding`, `kind`, reason `finding.unknown-field`); it was only
+  "unknown mail finding field".
+- **An order is not proposed twice.** Staging an `order` whose shop and number already wait in a proposed mail
+  findings batch is refused (`order.proposed`), as one already stored is (`order.duplicate`).
+
 ## 0.579.0 — 05.11.2026
 
 ### Added

package/dist/cli/findings-input.d.ts

@@ -2,5 +2,7 @@ import { type MailFindingsInput } from "../mail/findings.js";
 import { type FindingsInput, type MeetingFindingsInput } from "../meetings/index.js";
 export declare const parseMeetingFindingsJson: (text: string) => MeetingFindingsInput;
 export declare const parseEvidenceFindingsJson: (text: string) => FindingsInput;
+/** A mail findings batch as `mail findings add --dry-run` reads it: snake_case JSON, for `mailFindings.check`. */
+export declare const readMailFindingsJson: (text: string) => MailFindingsInput;
 /** A mail findings batch as `mail findings add` reads it: snake_case JSON, checked for shape before the store. */
 export declare const parseMailFindingsJson: (text: string) => MailFindingsInput;

package/dist/cli/findings-input.js

@@ -12,6 +12,14 @@ const keys = {
     due_date: "dueDate",
     unit_price: "unitPrice",
     supplier_name: "supplierName",
+    counterparty_name: "counterpartyName",
+    counterparty_email: "counterpartyEmail",
+    payer_name: "payerName",
+    payer_email: "payerEmail",
+    payee_name: "payeeName",
+    payee_email: "payeeEmail",
+    customer_name: "customerName",
+    customer_email: "customerEmail",
     order_date: "orderDate",
     fulfilled_date: "fulfilledDate",
     external_id: "externalId",
@@ -50,5 +58,7 @@ const parseFindingsJson = (text, label, validate) => {
 };
 export const parseMeetingFindingsJson = (text) => parseFindingsJson(text, "meeting findings", validateMeetingFindings);
 export const parseEvidenceFindingsJson = (text) => parseFindingsJson(text, "evidence findings", validateEvidenceFindings);
+/** A mail findings batch as `mail findings add --dry-run` reads it: snake_case JSON, for `mailFindings.check`. */
+export const readMailFindingsJson = (text) => parseFindingsJson(text, "mail findings", (input) => input);
 /** A mail findings batch as `mail findings add` reads it: snake_case JSON, checked for shape before the store. */
 export const parseMailFindingsJson = (text) => parseFindingsJson(text, "mail findings", validateMailFindings);

package/dist/cli/index.d.ts

@@ -75,7 +75,7 @@ export { admittedUnderLock, changesAuthority, changesAuthorityAt, changesAuthori
 export { type CliEntry, type EntryContext, type EntryIo, openBrowser, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./findings-input.js";
+export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, readMailFindingsJson, } from "./findings-input.js";
 export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";

package/dist/cli/index.js

@@ -66,7 +66,7 @@ export { admittedUnderLock, changesAuthority, changesAuthorityAt, changesAuthori
 export { openBrowser, startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, } from "./findings-input.js";
+export { parseEvidenceFindingsJson, parseMailFindingsJson, parseMeetingFindingsJson, readMailFindingsJson, } from "./findings-input.js";
 export { askSetupQuestions, asksAtStart, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";

package/dist/entities/index.d.ts

@@ -5988,7 +5988,9 @@ export declare const ENTITIES: {
                 }, undefined>, undefined>;
                 readonly kind: v.LiteralSchema<"invoice", undefined>;
                 readonly direction: v.PicklistSchema<readonly ["receivable", "payable"], undefined>;
-                readonly counterparty: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+                readonly counterparty: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly counterparty_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly counterparty_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly currency: v.StringSchema<undefined>;
                 readonly lines: v.ArraySchema<v.StrictObjectSchema<{
                     readonly description: v.StringSchema<undefined>;
@@ -6011,7 +6013,11 @@ export declare const ENTITIES: {
                 readonly kind: v.LiteralSchema<"payment", undefined>;
                 readonly direction: v.PicklistSchema<readonly ["in", "out"], undefined>;
                 readonly payer: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly payer_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly payer_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly payee: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly payee_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly payee_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly amount: v.StringSchema<undefined>;
                 readonly currency: v.StringSchema<undefined>;
                 readonly date: v.StringSchema<undefined>;
@@ -6031,6 +6037,8 @@ export declare const ENTITIES: {
                 readonly kind: v.LiteralSchema<"order", undefined>;
                 readonly purpose: v.PicklistSchema<readonly ["personal", "business", "client", "other"], undefined>;
                 readonly customer: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly customer_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly customer_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly supplier: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly supplier_name: v.StringSchema<undefined>;
                 readonly number: v.OptionalSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/mail-findings.d.ts

@@ -93,7 +93,10 @@ export declare const mailFindings: v.StrictObjectSchema<{
             }, undefined>, undefined>;
             readonly kind: v.LiteralSchema<"invoice", undefined>;
             readonly direction: v.PicklistSchema<readonly ["receivable", "payable"], undefined>;
-            readonly counterparty: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+            readonly counterparty: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            /** A counterparty the store may not hold yet; the owner's accept finds its organization or makes one. */
+            readonly counterparty_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly counterparty_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly currency: v.StringSchema<undefined>;
             readonly lines: v.ArraySchema<v.StrictObjectSchema<{
                 readonly description: v.StringSchema<undefined>;
@@ -116,7 +119,11 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly kind: v.LiteralSchema<"payment", undefined>;
             readonly direction: v.PicklistSchema<readonly ["in", "out"], undefined>;
             readonly payer: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            readonly payer_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly payer_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly payee: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            readonly payee_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly payee_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly amount: v.StringSchema<undefined>;
             readonly currency: v.StringSchema<undefined>;
             readonly date: v.StringSchema<undefined>;
@@ -136,6 +143,8 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly kind: v.LiteralSchema<"order", undefined>;
             readonly purpose: v.PicklistSchema<readonly ["personal", "business", "client", "other"], undefined>;
             readonly customer: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            readonly customer_name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly customer_email: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly supplier: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly supplier_name: v.StringSchema<undefined>;
             readonly number: v.OptionalSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/mail-findings.js

@@ -55,7 +55,10 @@ const finding = v.variant("kind", [
         ...base,
         kind: v.literal("invoice"),
         direction: v.picklist(INVOICE_DIRECTIONS),
-        counterparty: reference,
+        counterparty: v.optional(reference),
+        /** A counterparty the store may not hold yet; the owner's accept finds its organization or makes one. */
+        counterparty_name: v.optional(text),
+        counterparty_email: v.optional(text),
         currency: text,
         lines: v.array(v.strictObject({
             description: text,
@@ -75,7 +78,11 @@ const finding = v.variant("kind", [
         kind: v.literal("payment"),
         direction: v.picklist(MONEY_DIRECTIONS),
         payer: v.optional(reference),
+        payer_name: v.optional(text),
+        payer_email: v.optional(text),
         payee: v.optional(reference),
+        payee_name: v.optional(text),
+        payee_email: v.optional(text),
         amount: text,
         currency: text,
         date: text,
@@ -89,6 +96,8 @@ const finding = v.variant("kind", [
         kind: v.literal("order"),
         purpose: v.picklist(ORDER_PURPOSES),
         customer: v.optional(reference),
+        customer_name: v.optional(text),
+        customer_email: v.optional(text),
         supplier: v.optional(reference),
         supplier_name: text,
         number: v.optional(text),

package/dist/errors/reasons.js

@@ -62,6 +62,9 @@ const OTHERS = [
     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("mail-findings.dedicated-review", "review mail findings through the dedicated findings command"),
+    validation("mail-findings.invalid", "a checked mail findings batch would be refused; details.problems names why, finding by finding"),
+    validation("mail-findings.key-used", "the findings batch key was already used for different input"),
+    validation("finding.unknown-field", "a finding has a field its kind does not take"),
     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"],
     ["extraction.invalid-proposals", "invalid_response", "the model's memory proposals could not be used"],
@@ -200,6 +203,7 @@ const OTHERS = [
     validation("money.currency", "the currency is not one the store keeps money in"),
     validation("money.quantity", "the quantity is not a decimal above 0"),
     validation("order.duplicate", "the shop's order with this number is already stored; change its status instead"),
+    validation("order.proposed", "the shop's order with this number already waits for the owner in a findings batch"),
     validation("order.field", "a field of the order is not valid"),
     validation("order.source-url", "an order's source URL is not an http or https address"),
     ["order.not-found", "not_found", "no stored order of that shop has that number"],

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

@@ -15,6 +15,8 @@ export interface MailMount {
     acknowledge?: string;
     /** `null`: the host mounts no thread read, so a review offers none. */
     conversation?: string | null;
+    /** The host's command that stages a findings batch with `--key`; `review --holder` then gives that key as a step. */
+    findings?: string;
     /** In snake_case, as a step names it: memo's `source`, with `email:<account>`. */
     mailbox?: {
         option: string;

package/dist/mail/cli/review.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { defineQuery } from "@wirecat/cli-base/query";
-import { defineSteps, stepOf } from "@wirecat/cli-base/standards";
+import { defineSteps, MAX_NEXT_STEPS, stepOf, } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
 import { environmentOf, outputFor } from "../../cli/context.js";
 import { LOCAL_READ } from "../../cli/effects.js";
@@ -36,7 +36,18 @@ export const MAIL_REVIEW_QUERY = defineQuery({
 /** The mail review's steps where a host mounted them; a host lists them beside its own so its step checks know them. */
 export const mailReviewSteps = (mount = {}) => {
     const mailbox = mount.mailbox ? [{ name: mount.mailbox.option, required: true }] : [];
+    const findings = mount.findings
+        ? [
+            {
+                id: "mail-findings.add",
+                command: mount.findings,
+                args: [{ name: "key", required: true }, ...mailbox],
+                why: "stage what these emails ask under this key, before acknowledging them",
+            },
+        ]
+        : [];
     return defineSteps([
+        ...findings,
         {
             id: "mail-messages.acknowledge",
             command: mount.acknowledge ?? "messages acknowledge",
@@ -197,7 +208,12 @@ const holderReview = async (command, mail, holder, query) => {
     const step = stepsFor(mail.mount, mailbox);
     const answer = reviewAnswer(found, mailbox, true, step);
     const skipped = Object.entries(read.skipped).filter(([, count]) => count > 0);
-    answer.next = [...step("mail-messages.acknowledge", { holder, cursor: read.cursor }), ...(answer.next ?? [])];
+    const stage = read.findingsKey === undefined ? [] : step("mail-findings.add", { key: read.findingsKey });
+    answer.next = [
+        ...stage,
+        ...step("mail-messages.acknowledge", { holder, cursor: read.cursor }),
+        ...(answer.next ?? []),
+    ].slice(0, MAX_NEXT_STEPS);
     answer.missing = [
         ...(answer.missing ?? []),
         ...(read.held > 0 ? [{ field: "items", why: `${read.held} partial emails held until they are whole` }] : []),
@@ -217,7 +233,7 @@ const holderReview = async (command, mail, holder, query) => {
     const output = outputFor(command);
     renderAnswer(command, output, answer, () => {
         output.renderer.note(read.mark
-            ? `${holder}: past ${read.mark.throughId}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
+            ? `${holder}: past ${read.mark.throughId}; findings key ${read.findingsKey}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
         return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`).join("");
     });

package/dist/mail/findings.d.ts

@@ -45,8 +45,15 @@ export interface MailNewContactFinding extends Cited {
 export interface MailInvoiceFinding extends Cited {
     kind: "invoice";
     direction: (typeof INVOICE_DIRECTIONS)[number];
-    /** `person:` or `organization:`. */
-    counterparty: string;
+    /** `person:` or `organization:`; or `counterpartyName`, never both. */
+    counterparty?: string;
+    /**
+     * A party the store may not hold yet: on the owner's accept, the organization its `counterpartyEmail` or that
+     * address's domain belongs to, else the one of exactly this name, else a new company of this name.
+     */
+    counterpartyName?: string;
+    /** The party's own address, which a cited email was sent from or to. */
+    counterpartyEmail?: string;
     currency: string;
     lines: {
         description: string;
@@ -66,8 +73,13 @@ export interface MailInvoiceFinding extends Cited {
 export interface MailPaymentFinding extends Cited {
     kind: "payment";
     direction: (typeof MONEY_DIRECTIONS)[number];
+    /** Each party a reference, or a name and an optional address as an invoice's `counterpartyName` is. */
     payer?: string;
+    payerName?: string;
+    payerEmail?: string;
     payee?: string;
+    payeeName?: string;
+    payeeEmail?: string;
     amount: string;
     currency: string;
     /** `YYYY-MM-DD`. */
@@ -88,6 +100,9 @@ export interface MailOrderFinding extends Cited {
     purpose: (typeof ORDER_PURPOSES)[number];
     /** Whom it is for; the owner when left out. */
     customer?: string;
+    /** A customer the store may not hold yet, as an invoice's `counterpartyName` is. */
+    customerName?: string;
+    customerEmail?: string;
     supplier?: string;
     supplierName: string;
     number?: string;
@@ -116,14 +131,30 @@ export interface MailOrderUpdateFinding extends Cited {
 export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding | MailInvoiceFinding | MailPaymentFinding | MailOrderFinding | MailOrderUpdateFinding;
 export interface MailFindingsInput {
     schemaVersion: 1;
-    /** `<holder>:<through_id>`: one batch per run of a holder over the mail it was given. */
+    /**
+     * `<holder>:<through_id>`, with `-r<resets>` after the owner moved the mark back: one batch per run of a holder over
+     * the mail it was given. `review --holder` gives it.
+     */
     key: string;
     extractor: string;
     findings: MailFinding[];
 }
+export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
+/** Why one finding, or the batch when `finding` is null, would be refused. */
+export interface MailFindingProblem {
+    finding: string | null;
+    kind: string | null;
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export declare const mailFindingProblem: (raw: unknown, error: unknown) => MailFindingProblem;
 /**
- * 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.
+ * `validateMailFindings` finding by finding: the envelope still refuses the whole batch, but a bad finding no longer
+ * hides the next one, so `mail findings add --dry-run` names every problem at once.
  */
-export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
+export declare const checkMailFindings: (input: MailFindingsInput) => {
+    batch: MailFindingsInput;
+    problems: MailFindingProblem[];
+};
 export declare const mailFindingFingerprint: ({ id: _id, ...finding }: MailFinding) => string;

package/dist/mail/findings.js

@@ -1,4 +1,4 @@
-import { CliError } from "@wirecat/cli-base";
+import { CliError, isCliError } from "@wirecat/cli-base";
 import { EXTERNAL_ID_CHARS, externalIdOf, SOURCE_URL_CHARS, sourceUrlOf } from "../domain/external-links.js";
 import { INVOICE_DIRECTIONS, MONEY_DIRECTIONS } from "../domain/finance.js";
 import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
@@ -64,8 +64,21 @@ const one = (raw, ids) => {
         return validateFinding(raw, RULES, ids);
     if (raw.kind === "task") {
         const { externalId, sourceUrl, ...task } = raw;
+        let checked;
+        try {
+            checked = validateFinding(task, RULES, ids);
+        }
+        catch (error) {
+            if (!isCliError(error) || error.details.reason !== "finding.unknown-field")
+                throw error;
+            const allowed = [...error.details.allowed, "external_id", "source_url"];
+            throw new CliError("validation_error", error.message.replace(/; it takes .*$/, `; it takes ${allowed.join(", ")}`), {
+                ...error.details,
+                allowed,
+            });
+        }
         return {
-            ...validateFinding(task, RULES, ids),
+            ...checked,
             ...optional("externalId", externalId, (value) => {
                 const { provider, id } = externalIdOf(findingText(value, EXTERNAL_ID_CHARS + 40));
                 return `${provider}:${id}`;
@@ -81,6 +94,22 @@ const one = (raw, ids) => {
             return invalid(`${what} is not a reference of the kind it takes: ${text}`);
         return text;
     };
+    /** A party as a `person:`/`organization:` reference, or as `<field>_name` with an optional `<field>_email`. */
+    const party = (field, what) => {
+        const [given, name, email] = [raw[field], raw[`${field}Name`], raw[`${field}Email`]];
+        if (given !== undefined && name !== undefined)
+            return invalid(`${what} is ${field} or ${field}_name, not both`);
+        if (email !== undefined && name === undefined)
+            return invalid(`${field}_email comes with ${field}_name`);
+        return {
+            ...optional(field, given, (value) => reference(value, PARTY, what)),
+            ...optional(`${field}Name`, name, (value) => word(value, 200)),
+            ...optional(`${field}Email`, email, (value) => {
+                const address = findingText(value, 320).toLowerCase();
+                return ADDRESS.test(address) ? address : invalid(`${field}_email is an email address`);
+            }),
+        };
+    };
     switch (raw.kind) {
         case "task_update": {
             findingFields(raw, ["id", "kind", "task", "change", "dueAt", "detail", "reason", "evidence"], RULES.singular);
@@ -155,6 +184,8 @@ const one = (raw, ids) => {
                 "kind",
                 "direction",
                 "counterparty",
+                "counterpartyName",
+                "counterpartyEmail",
                 "currency",
                 "lines",
                 "total",
@@ -171,7 +202,7 @@ const one = (raw, ids) => {
                 if (!line || typeof line !== "object")
                     return invalid("an invoice line is an object");
                 const fields = line;
-                findingFields(fields, ["description", "quantity", "unitPrice", "amount"], "invoice line");
+                findingFields(fields, ["description", "quantity", "unitPrice", "amount"], "invoice line", raw);
                 return {
                     description: word(fields.description, 500),
                     ...optional("quantity", fields.quantity, (value) => word(value, 20)),
@@ -183,7 +214,9 @@ const one = (raw, ids) => {
                 id,
                 kind: "invoice",
                 direction: oneOf(raw.direction, INVOICE_DIRECTIONS, "an invoice's direction"),
-                counterparty: reference(raw.counterparty, PARTY, "an invoice's counterparty"),
+                ...(raw.counterparty === undefined && raw.counterpartyName === undefined
+                    ? invalid("an invoice names its counterparty: counterparty person:N|organization:N, or counterparty_name")
+                    : party("counterparty", "an invoice's counterparty")),
                 currency: word(raw.currency, 3),
                 lines,
                 ...optional("total", raw.total, (value) => word(value, 30)),
@@ -201,7 +234,11 @@ const one = (raw, ids) => {
                 "kind",
                 "direction",
                 "payer",
+                "payerName",
+                "payerEmail",
                 "payee",
+                "payeeName",
+                "payeeEmail",
                 "amount",
                 "currency",
                 "date",
@@ -219,7 +256,7 @@ const one = (raw, ids) => {
                     if (!share || typeof share !== "object")
                         return invalid("an allocation is an invoice and an amount");
                     const fields = share;
-                    findingFields(fields, ["invoice", "amount"], "allocation");
+                    findingFields(fields, ["invoice", "amount"], "allocation", raw);
                     return {
                         invoice: reference(fields.invoice, INVOICE, "an allocation's invoice"),
                         amount: word(fields.amount, 30),
@@ -230,8 +267,8 @@ const one = (raw, ids) => {
                 id,
                 kind: "payment",
                 direction: oneOf(raw.direction, MONEY_DIRECTIONS, "a payment's direction"),
-                ...optional("payer", raw.payer, (value) => reference(value, PARTY, "a payment's payer")),
-                ...optional("payee", raw.payee, (value) => reference(value, PARTY, "a payment's payee")),
+                ...party("payer", "a payment's payer"),
+                ...party("payee", "a payment's payee"),
                 amount: word(raw.amount, 30),
                 currency: word(raw.currency, 3),
                 date: word(raw.date, 10),
@@ -248,6 +285,8 @@ const one = (raw, ids) => {
                 "kind",
                 "purpose",
                 "customer",
+                "customerName",
+                "customerEmail",
                 "supplier",
                 "supplierName",
                 "number",
@@ -267,7 +306,7 @@ const one = (raw, ids) => {
                 id,
                 kind: "order",
                 purpose: oneOf(raw.purpose, ORDER_PURPOSES, "an order's purpose"),
-                ...optional("customer", raw.customer, (value) => reference(value, PARTY, "an order's customer")),
+                ...party("customer", "an order's customer"),
                 ...optional("supplier", raw.supplier, (value) => reference(value, PARTY, "an order's supplier")),
                 supplierName: word(raw.supplierName, 200),
                 ...optional("number", raw.number, (value) => word(value, 80)),
@@ -308,10 +347,48 @@ const one = (raw, ids) => {
  * 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.
  */
+const KEY = /^[a-z0-9][a-z0-9-]{0,39}:[1-9]\d*(-r[1-9]\d*)?$/;
+const KEY_SHAPE = "a mail findings key is the one `review --holder` gave: <holder>:<through_id>, and -r<resets> after a reset, " +
+    "such as mail-triage:9123456 or mail-triage:9123456-r1";
 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");
+    if (!KEY.test(batch.key))
+        return invalid(KEY_SHAPE);
     return batch;
 };
+export const mailFindingProblem = (raw, error) => {
+    if (!isCliError(error))
+        throw error;
+    const fields = raw && typeof raw === "object" ? raw : {};
+    const details = Object.fromEntries(Object.entries(error.details).filter(([key]) => key !== "finding" && key !== "kind"));
+    return {
+        finding: typeof fields.id === "string" ? fields.id : null,
+        kind: typeof fields.kind === "string" ? fields.kind : null,
+        code: error.code,
+        message: error.message,
+        ...(Object.keys(details).length ? { details } : {}),
+    };
+};
+/**
+ * `validateMailFindings` finding by finding: the envelope still refuses the whole batch, but a bad finding no longer
+ * hides the next one, so `mail findings add --dry-run` names every problem at once.
+ */
+export const checkMailFindings = (input) => {
+    const problems = [];
+    const batch = validateBatch(input, RULES, MAIL_FINDINGS_PER_RUN, (finding, ids) => {
+        try {
+            return one(finding, ids);
+        }
+        catch (error) {
+            problems.push(mailFindingProblem(finding, error));
+            return undefined;
+        }
+    });
+    if (!KEY.test(batch.key))
+        problems.push({ finding: null, kind: null, code: "validation_error", message: KEY_SHAPE });
+    return {
+        batch: { ...batch, findings: batch.findings.filter((one) => one !== undefined) },
+        problems,
+    };
+};
 export const mailFindingFingerprint = ({ id: _id, ...finding }) => findingHash(finding);

package/dist/mail/marks.d.ts

@@ -22,6 +22,8 @@ export interface MailMark {
     suspicious: number[];
     read: number;
     skipped: Record<SkipReason, number>;
+    /** How often the owner moved the mark back: a findings key names it, so a run after a reset never reuses one. */
+    resets: number;
     /** ms. */
     updatedAt: number;
 }
@@ -30,6 +32,12 @@ export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder:
 export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Promise<MailMark[]>;
 /** 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;
+/**
+ * The findings key of one run: `<holder>:<through_id>`, and `-r<resets>` once the owner moved the mark back, so the
+ * runs after a reset never reach a key a batch staged before it holds. The same review gives the same key: a retry
+ * of one run stages nothing twice.
+ */
+export declare const findingsKeyOf: (holder: string, throughId: number, resets: number) => string;
 /** A bulk email that is not surely a newsletter: the holder gets its subject and first lines only. */
 export interface BulkExcerpt {
     email: StoredHit;
@@ -45,6 +53,8 @@ export interface MarkRead {
     excerpts: BulkExcerpt[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
+    /** The key a findings batch over these emails takes; `undefined` while nothing is stored to read. */
+    findingsKey: string | undefined;
     /** More is stored after this batch: read again after acknowledging. */
     more: boolean;
     held: number;

package/dist/mail/marks.js

@@ -39,6 +39,7 @@ const parsed = (holder, value, at) => {
             suspicious: Array.isArray(saved.suspicious) ? saved.suspicious.filter((id) => typeof id === "number") : [],
             read: saved.read ?? 0,
             skipped: { ...noneSkipped(), ...saved.skipped },
+            resets: typeof saved.resets === "number" ? saved.resets : 0,
             updatedAt: at,
         };
     }
@@ -80,6 +81,12 @@ const verdict = (email, now) => {
 };
 /** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
 export const cursorOf = (throughId, readAt) => `${throughId}.${readAt}`;
+/**
+ * The findings key of one run: `<holder>:<through_id>`, and `-r<resets>` once the owner moved the mark back, so the
+ * runs after a reset never reach a key a batch staged before it holds. The same review gives the same key: a retry
+ * of one run stages nothing twice.
+ */
+export const findingsKeyOf = (holder, throughId, resets) => `${holder}:${throughId}${resets > 0 ? `-r${resets}` : ""}`;
 const parseCursor = (cursor) => {
     const match = /^(\d+)\.(\d+)$/.exec(cursor.trim());
     if (!match)
@@ -140,10 +147,14 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
         skipped: noneSkipped(),
         mark: saved,
     };
+    const keyed = (throughId) => ({
+        cursor: cursorOf(throughId, now),
+        findingsKey: throughId > 0 ? findingsKeyOf(holder, throughId, saved?.resets ?? 0) : undefined,
+    });
     if (!account)
-        return { ...empty, cursor: cursorOf(0, now) };
+        return { ...empty, ...keyed(0) };
     if (!saved)
-        return { ...empty, cursor: cursorOf(await store.mail.newestEmailId(account.id), now) };
+        return { ...empty, ...keyed(await store.mail.newestEmailId(account.id)) };
     const mark = after === undefined ? saved : { ...saved, throughId: after, held: [], suspicious: [] };
     const found = await store.mail.emailsAfter(account.id, mark.throughId, limit + 1, [...mark.held, ...mark.suspicious]);
     // Mail a running sync stored is read once that sync ended: it files bulk mail only at its end.
@@ -179,7 +190,7 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
         wanted: wanted.sort((a, b) => a - b),
         sorted: new Map([...sorted].filter(([, one]) => one.verdict === "excerpt")),
         oldestStoredAt,
-        cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
+        ...keyed(batch.at(-1)?.id ?? mark.throughId),
         more: newer.length > batch.length,
         held,
         skipped,
@@ -312,6 +323,7 @@ export const acknowledgeMark = async (store, mailbox, holder, cursor, now = Date
         suspicious: [...new Set(suspicious)].sort((a, b) => a - b).slice(-MOST_HELD),
         read,
         skipped,
+        resets: mark?.resets ?? 0,
     };
     await store.sync.setSyncState(mailbox, key, JSON.stringify(next));
     return { holder, ...next, updatedAt: now };
@@ -397,6 +409,7 @@ export const rewindMark = async (store, mailbox, holder, to, { now = Date.now(),
         suspicious: mark.suspicious.filter((id) => id <= through),
         read: mark.read,
         skipped: mark.skipped,
+        resets: mark.resets + 1,
     };
     if (!dry)
         await store.sync.setSyncState(mailbox, key, JSON.stringify(next));

package/dist/meetings/findings-rules.d.ts

@@ -65,7 +65,14 @@ export interface FindingsReceipt {
 }
 export declare const findingText: (value: unknown, limit: number) => string;
 export declare const findingHash: (value: unknown) => string;
-export declare const findingFields: (value: object, allowed: string[], noun: string) => void;
+/**
+ * Refuses a field `allowed` does not list, naming it, the finding it is in and what that kind takes: an agent fixes
+ * the batch from the message alone. `of` is the finding a nested object (an invoice line) belongs to.
+ */
+export declare const findingFields: (value: object, allowed: string[], noun: string, of?: {
+    id?: unknown;
+    kind?: unknown;
+}) => void;
 /** What differs between findings kinds: their wording and what one cited reference must look like. */
 export interface FindingsRules {
     /** "meeting findings" */

package/dist/meetings/findings-rules.js

@@ -12,9 +12,27 @@ export const findingText = (value, limit) => {
     return value.trim();
 };
 export const findingHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-export const findingFields = (value, allowed, noun) => {
-    if (Object.keys(value).some((key) => !allowed.includes(key)))
-        invalid(`unknown ${noun} field`);
+const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+/**
+ * Refuses a field `allowed` does not list, naming it, the finding it is in and what that kind takes: an agent fixes
+ * the batch from the message alone. `of` is the finding a nested object (an invoice line) belongs to.
+ */
+export const findingFields = (value, allowed, noun, of = value) => {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (!unknown.length)
+        return;
+    const fields = unknown.map(snakeCase);
+    const takes = allowed.map(snakeCase);
+    const id = typeof of.id === "string" ? of.id : null;
+    const kind = typeof of.kind === "string" ? of.kind : null;
+    const where = id || kind ? ` in ${[id, kind && `(${kind})`].filter(Boolean).join(" ")}` : "";
+    throw new CliError("validation_error", `unknown ${noun} field${fields.length > 1 ? "s" : ""} ${fields.join(", ")}${where}; it takes ${takes.join(", ")}`, {
+        reason: "finding.unknown-field",
+        fields,
+        allowed: takes,
+        ...(id ? { finding: id } : {}),
+        ...(kind ? { kind } : {}),
+    });
 };
 const SUBJECT = /^(person|organization|project):[1-9]\d*$|^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
 /** A finding's cited evidence: 1–8 distinct references in `rules`' form, each with a 64-hex fingerprint. */

package/dist/services/proposals/kinds/mail-findings.js

@@ -17,7 +17,7 @@ const summaryOf = (finding) => {
         case "new_contact":
             return `${finding.name} <${finding.address}>`;
         case "invoice":
-            return words("invoice", finding.number, finding.total, finding.currency, `· ${finding.reason}`);
+            return words("invoice", finding.number, finding.total, finding.currency, finding.counterpartyName, `· ${finding.reason}`);
         case "payment":
             return words("payment", finding.amount, finding.currency, finding.date, `· ${finding.reason}`);
         case "order":

package/dist/store/index.d.ts

@@ -16,7 +16,7 @@ export type { CacheDatabase, CacheStatement, OpenDatabase, SqlValue } from "./dr
 export { PRAGMAS } from "./driver.js";
 export { EVIDENCE_FINDINGS_KIND, type EvidenceFindingsBatch, type EvidenceFindingsDecider, type EvidenceFindingsReceipt, type EvidenceFindingsStore, validateEvidenceFindings, } from "./evidence-findings.js";
 export { ORGANIZATIONS_QUERY, organization, PROJECTS_QUERY, project, REMINDERS_QUERY, reminder, } from "./knowledge-query.js";
-export { MAIL_FINDINGS_KIND, type MailFindingsBatch, type MailFindingsStore } from "./mail-findings.js";
+export { MAIL_FINDINGS_KIND, type MailFindingsBatch, type MailFindingsCheck, type MailFindingsStore, } from "./mail-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

@@ -8,7 +8,7 @@ export { applyDocumentTransfer, previewDocumentTransfer } from "./document-trans
 export { PRAGMAS } from "./driver.js";
 export { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "./evidence-findings.js";
 export { ORGANIZATIONS_QUERY, organization, PROJECTS_QUERY, project, REMINDERS_QUERY, reminder, } from "./knowledge-query.js";
-export { MAIL_FINDINGS_KIND } from "./mail-findings.js";
+export { MAIL_FINDINGS_KIND, } from "./mail-findings.js";
 export { MIGRATIONS, migrate } from "./migrations.js";
 export { openCache } from "./open.js";
 export { storePath } from "./path.js";

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

@@ -1,4 +1,4 @@
-import type { MailFindingsInput } from "../mail/findings.js";
+import type { MailFindingProblem, MailFindingsInput } from "../mail/findings.js";
 import type { FindingOutcome, FindingsReceipt } from "../meetings/index.js";
 import type { Decider } from "./decisions.js";
 import type { AccountKey } from "./types.js";
@@ -23,6 +23,14 @@ export interface MailFindingsBatch {
     previous: FindingOutcome[];
     receipt: FindingsReceipt | null;
 }
+/** What `stage` would do with a batch, found without writing anything. */
+export interface MailFindingsCheck {
+    valid: boolean;
+    findings: number;
+    /** The batch `stage` would give back: an earlier one under this key with this same input, else null. */
+    batch: string | null;
+    problems: MailFindingProblem[];
+}
 /**
  * What an agent read in new mail — tasks, task updates, facts, memories, links, new contacts — cited and staged for
  * the owner, one batch per mailbox and run. Only the owner decides one: an agent's mail proposal never becomes the
@@ -33,6 +41,14 @@ export interface MailFindingsStore {
         bot: string;
         model?: string;
     }): Promise<MailFindingsBatch>;
+    /**
+     * Every check `stage` makes, the trial write of each invoice, payment and order included, rolled back: each
+     * finding's problem is listed, not only the first. Input is the decoded JSON, before `validateMailFindings`.
+     */
+    check(account: AccountKey, input: MailFindingsInput, agent: {
+        bot: string;
+        model?: string;
+    }): Promise<MailFindingsCheck>;
     get(id: string): Promise<MailFindingsBatch>;
     list(options?: {
         account?: AccountKey;

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

@@ -1,10 +1,12 @@
 import { CliError } from "@wirecat/cli-base";
 import { contextEvidenceFingerprint } from "../../context/evidence.js";
 import { parseLocator } from "../../domain/locator.js";
-import { MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, validateMailFindings, } from "../../mail/findings.js";
+import { checkMailFindings, MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, mailFindingProblem, validateMailFindings, } from "../../mail/findings.js";
+import { FREE_MAIL } from "../../mail/score.js";
 import { findingHash } from "../../meetings/index.js";
 import { assertMayDecide } from "../decisions.js";
 import { MAIL_FINDINGS_KIND } from "../mail-findings.js";
+import { fold } from "../normalize.js";
 import { financeOperationsOver } from "./finance.js";
 import { findingsAgent, findingsCoreOver } from "./findings-core.js";
 import { authorActor, linkEvidence, memoriesStoreOver } from "./memories.js";
@@ -139,6 +141,52 @@ export const mailFindingsStoreOver = (context) => {
         }
         return read;
     };
+    const organizationsOf = (sql, ...params) => [
+        ...new Set(database
+            .prepare(sql)
+            .all(...params)
+            .map((row) => Number(row.id))),
+    ];
+    const BY_ADDRESS = "SELECT o.id FROM organizations o JOIN organization_identities oi ON oi.organization_id = o.id " +
+        "JOIN identities i ON i.id = oi.identity_id WHERE o.deleted_at IS NULL AND i.provider = 'email' AND ";
+    /**
+     * The organization a finding names but does not reference: the one its address belongs to, else the one its
+     * company domain belongs to, else the one of exactly this name; else a new company. Its address joins it, so the
+     * next mail from it finds it. Only the owner's accept runs this for real; staging runs it and rolls it back.
+     */
+    const organizationNamed = (name, email) => {
+        const domain = email?.split("@")[1];
+        let found = email === undefined ? [] : organizationsOf(`${BY_ADDRESS}lower(i.external_id) = ?`, email);
+        if (!found.length && domain && !FREE_MAIL.has(domain))
+            found = organizationsOf(`${BY_ADDRESS}substr(lower(i.external_id), -length(?)) = ?`, `@${domain}`, `@${domain}`);
+        if (!found.length)
+            found = database
+                .prepare("SELECT id, name FROM organizations WHERE deleted_at IS NULL")
+                .all()
+                .filter((row) => fold(String(row.name)).trim() === fold(name).trim())
+                .map((row) => Number(row.id));
+        if (found.length > 1)
+            return invalid(`${found.length} organizations match ${name} (${found.map((id) => `organization:${id}`).join(", ")}); ` +
+                "name the one meant as a reference", "finance.party");
+        const at = now();
+        const id = found[0] ??
+            Number(database
+                .prepare("INSERT INTO organizations (kind, name, scope, created_at, updated_at) VALUES ('company', ?, 'work', ?, ?) RETURNING id")
+                .get(name, at, at)?.id);
+        if (email !== undefined) {
+            database
+                .prepare("INSERT INTO identities (provider, external_id, created_at, updated_at) VALUES ('email', ?, ?, ?) " +
+                "ON CONFLICT (provider, external_id) DO NOTHING")
+                .run(email, at, at);
+            database
+                .prepare("INSERT INTO organization_identities (identity_id, organization_id, method, author, created_at, updated_at) " +
+                "SELECT id, ?, 'mail-finding', 'owner', ?, ? FROM identities WHERE provider = 'email' AND external_id = ? " +
+                "ON CONFLICT (identity_id, organization_id) DO NOTHING")
+                .run(id, at, at, email);
+        }
+        return `organization:${id}`;
+    };
+    const partyOf = (reference, name, email) => reference ?? (name === undefined ? undefined : organizationNamed(name, email));
     /** The invoice, payment or order an accepted finding records: the owner's own entry, citing the mail it came from. */
     const entry = (finding, evidence) => {
         const by = "owner";
@@ -148,7 +196,7 @@ export const mailFindingsStoreOver = (context) => {
                     by,
                     evidence,
                     direction: finding.direction,
-                    counterparty: finding.counterparty,
+                    counterparty: partyOf(finding.counterparty, finding.counterpartyName, finding.counterpartyEmail),
                     currency: finding.currency,
                     lines: finding.lines,
                     ...(finding.total === undefined ? {} : { total: finding.total }),
@@ -158,22 +206,29 @@ export const mailFindingsStoreOver = (context) => {
                     ...(finding.project === undefined ? {} : { project: finding.project }),
                 });
             case "payment":
-                return () => finance.addPayment({
-                    by,
-                    evidence,
-                    direction: finding.direction,
-                    amount: finding.amount,
-                    currency: finding.currency,
-                    date: finding.date,
-                    ...(finding.payer === undefined ? {} : { payer: finding.payer }),
-                    ...(finding.payee === undefined ? {} : { payee: finding.payee }),
-                    ...(finding.reference === undefined ? {} : { reference: finding.reference }),
-                    ...(finding.allocations === undefined ? {} : { allocations: finding.allocations }),
-                    ...(finding.project === undefined ? {} : { project: finding.project }),
-                });
+                return () => {
+                    const payer = partyOf(finding.payer, finding.payerName, finding.payerEmail);
+                    const payee = partyOf(finding.payee, finding.payeeName, finding.payeeEmail);
+                    return finance.addPayment({
+                        by,
+                        evidence,
+                        direction: finding.direction,
+                        amount: finding.amount,
+                        currency: finding.currency,
+                        date: finding.date,
+                        ...(payer === undefined ? {} : { payer }),
+                        ...(payee === undefined ? {} : { payee }),
+                        ...(finding.reference === undefined ? {} : { reference: finding.reference }),
+                        ...(finding.allocations === undefined ? {} : { allocations: finding.allocations }),
+                        ...(finding.project === undefined ? {} : { project: finding.project }),
+                    });
+                };
             case "order": {
-                const { id: _id, kind: _kind, evidence: _cited, reason: _reason, ...fields } = finding;
-                return () => orders.add({ ...fields, by, evidence });
+                const { id: _id, kind: _kind, evidence: _cited, reason: _reason, customer: given, customerName, customerEmail, ...fields } = finding;
+                return () => {
+                    const customer = partyOf(given, customerName, customerEmail);
+                    return orders.add({ ...fields, ...(customer === undefined ? {} : { customer }), by, evidence });
+                };
             }
             default:
                 return undefined;
@@ -197,6 +252,26 @@ export const mailFindingsStoreOver = (context) => {
         .prepare("SELECT i.id, l.person_id FROM identities i LEFT JOIN identity_links l ON l.identity_id = i.id " +
         "WHERE i.provider = 'email' AND lower(i.external_id) = ?")
         .get(address.toLowerCase());
+    /** Whether `address` sent or received one of the emails `finding` cites. */
+    const inCitedMail = (address, finding, read) => {
+        const ids = finding.evidence.map(({ reference }) => Number(read.get(reference)?.id));
+        const marks = ids.map(() => "?").join(",");
+        return Boolean(database
+            .prepare(`SELECT 1 FROM emails WHERE id IN (${marks}) AND lower(from_address) = ? UNION ALL ` +
+            `SELECT 1 FROM email_recipients WHERE email_id IN (${marks}) AND lower(address) = ? LIMIT 1`)
+            .get(...ids, address, ...ids, address));
+    };
+    /** A proposed findings batch that already holds this shop's order with this number. */
+    const proposedOrder = (supplierName, number) => {
+        const shop = fold(supplierName).trim();
+        return database
+            .prepare("SELECT p.id, json_extract(f.value, '$.supplierName') AS shop FROM proposed_actions p, " +
+            "json_each(p.payload, '$.findings') f WHERE p.kind = ? AND p.status = 'proposed' " +
+            "AND json_extract(f.value, '$.kind') = 'order' AND trim(json_extract(f.value, '$.number')) = ?")
+            .all(MAIL_FINDINGS_KIND, number.trim())
+            .filter((row) => fold(String(row.shop)).trim() === shop)
+            .map((row) => String(row.id))[0];
+    };
     /** Whatever a finding names must be stored: a task to update, a subject, a link's ends, a contact's address. */
     const targets = (finding, read) => {
         const thing = (reference, what) => {
@@ -224,19 +299,27 @@ export const mailFindingsStoreOver = (context) => {
             case "invoice":
             case "payment":
             case "order":
+                for (const address of [
+                    "counterpartyEmail" in finding ? finding.counterpartyEmail : undefined,
+                    "payerEmail" in finding ? finding.payerEmail : undefined,
+                    "payeeEmail" in finding ? finding.payeeEmail : undefined,
+                    "customerEmail" in finding ? finding.customerEmail : undefined,
+                ])
+                    if (address !== undefined && !inCitedMail(address, finding, read))
+                        return invalid(`${address} neither sent nor received the mail finding ${finding.id} cites`);
+                if (finding.kind === "order" && finding.number !== undefined) {
+                    const waiting = proposedOrder(finding.supplierName, finding.number);
+                    if (waiting)
+                        return invalid(`order ${finding.number} from ${finding.supplierName} already waits for the owner in findings batch ` +
+                            `${waiting}; leave it out, or send an order_update once it is stored and its status changes`, "order.proposed");
+                }
                 wouldWrite(entry(finding, finding.evidence.map((one) => one.reference)));
                 return;
             case "order_update":
                 orderOfShop(context, finding.supplierName, finding.number);
                 return;
             case "new_contact": {
-                const ids = finding.evidence.map(({ reference }) => Number(read.get(reference)?.id));
-                const marks = ids.map(() => "?").join(",");
-                const named = database
-                    .prepare(`SELECT 1 FROM emails WHERE id IN (${marks}) AND lower(from_address) = ? UNION ALL ` +
-                    `SELECT 1 FROM email_recipients WHERE email_id IN (${marks}) AND lower(address) = ? LIMIT 1`)
-                    .get(...ids, finding.address, ...ids, finding.address);
-                if (!named)
+                if (!inCitedMail(finding.address, finding, read))
                     return invalid(`${finding.address} neither sent nor received the mail finding ${finding.id} cites`);
                 if (!identityOfAddress(finding.address))
                     throw new CliError("not_found", `no stored contact ${finding.address}`);
@@ -317,23 +400,31 @@ export const mailFindingsStoreOver = (context) => {
             }
         }
     };
+    /** The batch this agent already staged under the input's key: the same input's, or a refusal for another's. */
+    /** `whole` is false for a checked batch that lost findings to their problems: no staged input can equal it. */
+    const heldBatch = (account, input, by, whole = true) => {
+        const { actor } = authorActor(context, by);
+        const held = database
+            .prepare("SELECT id FROM proposed_actions WHERE account_id = ? AND kind = ? AND proposed_by_type = ? AND proposed_by_id = ? AND json_extract(payload, '$.key') = ? ORDER BY id LIMIT 1")
+            .get(account, MAIL_FINDINGS_KIND, actor.type, actor.id, input.key);
+        if (!held)
+            return undefined;
+        const proposal = load(String(held.id));
+        if (!whole || proposal.payload.inputHash !== findingHash({ input, model: by.model ?? null }))
+            return invalid(`the findings batch key ${input.key} was already used for different input (batch ${proposal.id}); ` +
+                "check a batch with --dry-run before staging it", "mail-findings.key-used");
+        return proposal;
+    };
     return {
         stage: async (key, raw, rawAgent) => {
             const input = validateMailFindings(raw);
             const by = findingsAgent(rawAgent);
             return write(database, () => {
                 const account = mailbox(key);
-                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 = ? AND kind = ? AND proposed_by_type = ? AND proposed_by_id = ? AND json_extract(payload, '$.key') = ? ORDER BY id LIMIT 1")
-                    .get(account, MAIL_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 held = heldBatch(account, input, by);
+                if (held)
+                    return view(held);
                 const read = cite(input.findings, account);
                 for (const finding of input.findings)
                     targets(finding, read);
@@ -348,6 +439,45 @@ export const mailFindingsStoreOver = (context) => {
                 }));
             });
         },
+        check: async (key, raw, rawAgent) => {
+            const { batch: input, problems } = checkMailFindings(raw);
+            const by = findingsAgent(rawAgent);
+            const batchProblem = (error) => problems.push(mailFindingProblem(null, error));
+            let batch = null;
+            // authorActor and the trial writes touch the store; everything here is rolled back.
+            wouldWrite(() => {
+                const account = mailbox(key);
+                try {
+                    batch = heldBatch(account, input, by, problems.length === 0)?.id ?? null;
+                }
+                catch (error) {
+                    batchProblem(error);
+                }
+                if (batch !== null)
+                    return;
+                const valid = [];
+                for (const finding of input.findings) {
+                    try {
+                        targets(finding, cite([finding], account));
+                        valid.push(finding);
+                    }
+                    catch (error) {
+                        problems.push(mailFindingProblem(finding, error));
+                    }
+                }
+                try {
+                    if (valid.length === input.findings.length)
+                        cite(valid, account);
+                    const fingerprints = valid.map(mailFindingFingerprint);
+                    if (new Set(fingerprints).size !== fingerprints.length)
+                        invalid("the batch contains duplicate findings");
+                }
+                catch (error) {
+                    batchProblem(error);
+                }
+            });
+            return { valid: problems.length === 0, findings: raw.findings?.length ?? 0, batch, problems };
+        },
         get: async (id) => view(load(id)),
         list: async ({ account, status, limit = 20, offset = 0 } = {}) => {
             if (status !== undefined && status !== "proposed" && status !== "reviewed")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.579.0",
+  "version": "0.581.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",