@wirecat/cli-core 0.578.0 → 0.580.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## 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
+
+- **An agent's new organization is a proposal for the owner: the `organization` proposal kind and
+  `proposeOrganization(store, { name, kind, scope? }, by)`.** It is stored in `proposed_actions` as
+  `organization_add`, so no schema change; `proposalRegistry` lists it in `review`, and confirming it adds the
+  organization (`made: ["organization:<id>"]`), rejecting it adds nothing. The owner still adds one directly with
+  `knowledge.addOrganization`. `ORGANIZATION_ADD_KIND` and `OrganizationProposal` are exported from `services`.
+
 ## 0.577.0 — 05.11.2026
 
 ### Added

package/dist/calendar/mcp/index.d.ts

@@ -10,13 +10,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -45,9 +45,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -58,9 +58,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -80,13 +80,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -115,9 +115,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -128,9 +128,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -150,13 +150,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -185,9 +185,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -198,9 +198,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -220,13 +220,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -255,9 +255,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -268,9 +268,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;

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/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;
@@ -121,9 +136,22 @@ export interface MailFindingsInput {
     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,47 @@ 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*$/;
+const KEY_SHAPE = "a mail findings key is <holder>:<through_id>, such as mail-triage:9123456";
 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/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. */