@wirecat/cli-core 0.581.0 → 0.583.0

package/dist/mail/findings.js

@@ -5,7 +5,7 @@ import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
 import { formatLocator, parseLocator } from "../domain/locator.js";
 import { ORDER_PURPOSES, ORDER_STATUSES } from "../domain/orders.js";
 import { parseReference } from "../domain/references.js";
-import { findingFields, findingHash, findingId, findingText, meetingTimestamp, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
+import { findingFields, findingHash, findingId, findingNeeds, findingText, meetingTimestamp, snakeCase, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
 export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
 /** At most this many findings in one run's batch, and per sender in it. */
 export const MAIL_FINDINGS_PER_RUN = 30;
@@ -30,6 +30,90 @@ const RULES = {
     anySubject: true,
     inboxTasks: true,
 };
+/**
+ * What each kind takes besides `id`, `kind` and `evidence`, in the order the validator reads them: `needs` it refuses
+ * without, `may` it takes. `--help`, `details.allowed` and `details.needs` all read this table, so they cannot drift
+ * from the checks. Some fields go together (due_at with due_evidence) or replace each other (counterparty or
+ * counterparty_name); the check of each kind says which.
+ */
+export const MAIL_FINDING_FIELDS = {
+    task: {
+        needs: ["type", "title", "reason", "commitment"],
+        may: ["project", "dueAt", "dueEvidence", "assignee", "assigneeEvidence", "externalId", "sourceUrl"],
+    },
+    task_update: { needs: ["task", "change", "reason"], may: ["dueAt", "detail"] },
+    fact: { needs: ["type", "statement", "reason"], may: ["subject", "project"] },
+    memory: { needs: ["memoryKind", "scope", "body", "reason"], may: ["subject", "project"] },
+    link: { needs: ["from", "to", "reason"], may: [] },
+    new_contact: { needs: ["address", "name", "reason"], may: [] },
+    invoice: {
+        needs: ["direction", "currency", "lines", "reason"],
+        may: [
+            "counterparty",
+            "counterpartyName",
+            "counterpartyEmail",
+            "total",
+            "number",
+            "issueDate",
+            "dueDate",
+            "project",
+        ],
+    },
+    payment: {
+        needs: ["direction", "amount", "currency", "date", "reason"],
+        may: [
+            "payer",
+            "payerName",
+            "payerEmail",
+            "payee",
+            "payeeName",
+            "payeeEmail",
+            "reference",
+            "allocations",
+            "project",
+        ],
+    },
+    order: {
+        needs: ["purpose", "supplierName", "reason"],
+        may: [
+            "customer",
+            "customerName",
+            "customerEmail",
+            "supplier",
+            "number",
+            "total",
+            "currency",
+            "status",
+            "orderDate",
+            "fulfilledDate",
+            "invoice",
+            "payment",
+            "project",
+            "sourceUrl",
+        ],
+    },
+    order_update: { needs: ["supplierName", "number", "status", "reason"], may: ["date"] },
+};
+const MAIL_FINDING_KINDS = Object.keys(MAIL_FINDING_FIELDS);
+/** The fixed values a field takes, shown in `--help` beside it; the checks read the same lists. */
+const VALUES = {
+    task: { type: ["bug", "feature", "chore"], commitment: ["explicit", "inferred"] },
+    task_update: { change: ["close", "due", "detail"] },
+    memory: { memoryKind: MEMORY_KINDS, scope: MEMORY_SCOPES },
+    invoice: { direction: INVOICE_DIRECTIONS },
+    payment: { direction: MONEY_DIRECTIONS },
+    order: { purpose: ORDER_PURPOSES, status: ORDER_STATUSES },
+    order_update: { status: ORDER_STATUSES },
+};
+/** One line per kind, `kind: needed fields; optional ones`, for `mail findings add --help`. */
+export const mailFindingFieldsHelp = () => MAIL_FINDING_KINDS.map((kind) => {
+    const { needs, may } = MAIL_FINDING_FIELDS[kind];
+    const named = (field) => {
+        const values = VALUES[kind]?.[field];
+        return values ? `${snakeCase(field)} ${values.join("|")}` : snakeCase(field);
+    };
+    return `  ${kind}: ${needs.map(named).join(", ")}${may.length ? `; optional ${may.map(named).join(", ")}` : ""}`;
+}).join("\n");
 const typeOf = (reference) => {
     try {
         const parsed = parseReference(reference);
@@ -60,23 +144,18 @@ const optional = (key, value, read) => (value === undefined ? {} : { [key]: read
 const one = (raw, ids) => {
     if (!raw || typeof raw !== "object")
         return invalid("a finding is an object");
-    if (raw.kind === "fact")
-        return validateFinding(raw, RULES, ids);
+    if (!MAIL_FINDING_KINDS.includes(raw.kind))
+        return invalid(`a mail finding is a ${MAIL_FINDING_KINDS.join(", ")}`);
+    const { needs, may } = MAIL_FINDING_FIELDS[raw.kind];
+    findingFields(raw, ["id", "kind", ...needs, ...may, "evidence"], RULES.singular);
+    findingNeeds(raw, needs, RULES.singular);
+    if (raw.kind === "fact") {
+        const { reason, ...fact } = raw;
+        return { ...validateFinding(fact, RULES, ids), reason: findingText(reason, 2000) };
+    }
     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,
-            });
-        }
+        const checked = validateFinding(task, RULES, ids);
         return {
             ...checked,
             ...optional("externalId", externalId, (value) => {
@@ -112,7 +191,6 @@ const one = (raw, ids) => {
     };
     switch (raw.kind) {
         case "task_update": {
-            findingFields(raw, ["id", "kind", "task", "change", "dueAt", "detail", "reason", "evidence"], RULES.singular);
             const task = reference(raw.task, /^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/, "a task update's task");
             const change = raw.change;
             if (change !== "close" && change !== "due" && change !== "detail")
@@ -135,7 +213,6 @@ const one = (raw, ids) => {
             };
         }
         case "memory": {
-            findingFields(raw, ["id", "kind", "memoryKind", "scope", "body", "subject", "project", "evidence"], RULES.singular);
             if (!MEMORY_KINDS.includes(raw.memoryKind))
                 return invalid(`a memory's memory_kind is ${MEMORY_KINDS.join(", ")}`);
             if (!MEMORY_SCOPES.includes(raw.scope))
@@ -152,11 +229,11 @@ const one = (raw, ids) => {
                     ? {}
                     : { subject: reference(raw.subject, /^(person|organization|project):[1-9]\d*$/, "a memory's subject") }),
                 ...(raw.project === undefined ? {} : { project: reference(raw.project, /^project:[1-9]\d*$/, "a project") }),
+                reason: findingText(raw.reason, 2000),
                 evidence,
             };
         }
         case "link": {
-            findingFields(raw, ["id", "kind", "from", "to", "reason", "evidence"], RULES.singular);
             const from = findingText(raw.from, 400);
             const to = findingText(raw.to, 80);
             const wanted = LINKS[typeOf(from) ?? ""];
@@ -165,7 +242,6 @@ const one = (raw, ids) => {
             return { id, kind: "link", from, to, reason: findingText(raw.reason, 2000), evidence };
         }
         case "new_contact": {
-            findingFields(raw, ["id", "kind", "address", "name", "reason", "evidence"], RULES.singular);
             const address = findingText(raw.address, 320).toLowerCase();
             if (!ADDRESS.test(address))
                 return invalid("a new contact's address is an email address");
@@ -174,28 +250,11 @@ const one = (raw, ids) => {
                 kind: "new_contact",
                 address,
                 name: findingText(raw.name, 200),
-                ...(raw.reason === undefined ? {} : { reason: findingText(raw.reason, 2000) }),
+                reason: findingText(raw.reason, 2000),
                 evidence,
             };
         }
         case "invoice": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "direction",
-                "counterparty",
-                "counterpartyName",
-                "counterpartyEmail",
-                "currency",
-                "lines",
-                "total",
-                "number",
-                "issueDate",
-                "dueDate",
-                "project",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             if (!Array.isArray(raw.lines) || raw.lines.length < 1 || raw.lines.length > 50)
                 return invalid("an invoice finding has 1–50 lines");
             const lines = raw.lines.map((line) => {
@@ -229,25 +288,6 @@ const one = (raw, ids) => {
             };
         }
         case "payment": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "direction",
-                "payer",
-                "payerName",
-                "payerEmail",
-                "payee",
-                "payeeName",
-                "payeeEmail",
-                "amount",
-                "currency",
-                "date",
-                "reference",
-                "allocations",
-                "project",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             let allocations;
             if (raw.allocations !== undefined) {
                 if (!Array.isArray(raw.allocations) || raw.allocations.length < 1 || raw.allocations.length > 8)
@@ -280,28 +320,6 @@ const one = (raw, ids) => {
             };
         }
         case "order": {
-            findingFields(raw, [
-                "id",
-                "kind",
-                "purpose",
-                "customer",
-                "customerName",
-                "customerEmail",
-                "supplier",
-                "supplierName",
-                "number",
-                "total",
-                "currency",
-                "status",
-                "orderDate",
-                "fulfilledDate",
-                "invoice",
-                "payment",
-                "project",
-                "sourceUrl",
-                "reason",
-                "evidence",
-            ], RULES.singular);
             return {
                 id,
                 kind: "order",
@@ -324,7 +342,6 @@ const one = (raw, ids) => {
             };
         }
         case "order_update": {
-            findingFields(raw, ["id", "kind", "supplierName", "number", "status", "date", "reason", "evidence"], RULES.singular);
             const status = oneOf(raw.status, ORDER_STATUSES, "an order update's status");
             if (raw.date !== undefined && status !== "delivered")
                 return invalid("only a delivered order update gives date");
@@ -340,7 +357,7 @@ const one = (raw, ids) => {
             };
         }
         default:
-            return invalid("a mail finding is a task, task_update, fact, memory, link, new_contact, invoice, payment, order or order_update");
+            return invalid(`a mail finding is a ${MAIL_FINDING_KINDS.join(", ")}`);
     }
 };
 /**

package/dist/mail/index.d.ts

@@ -3,7 +3,7 @@ export { mailAccountKey } from "./account-key.js";
 export { DEFAULT_ATTACHMENT_POLICY, type MailAttachmentPolicy, POLICY_SKIPS } from "./attachments.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
-export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
+export { MAIL_FINDING_FIELDS, MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFieldsHelp, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";

package/dist/mail/index.js

@@ -3,7 +3,7 @@ export { mailAccountKey } from "./account-key.js";
 export { DEFAULT_ATTACHMENT_POLICY, POLICY_SKIPS } from "./attachments.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
-export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
+export { MAIL_FINDING_FIELDS, MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFieldsHelp, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";

package/dist/mail/marks.js

@@ -398,13 +398,12 @@ export const rewindMark = async (store, mailbox, holder, to, { now = Date.now(),
         skipped: count((said) => said !== "read" && said !== "held" && said !== "bulk"),
         dry,
     };
-    if (through >= mark.throughId)
-        return { mark, ...answer };
-    const [last] = through > 0 ? await store.mail.emailsBefore(account.id, through + 1, 1) : [];
-    const at = last?.id === through ? last.at : null;
+    // A reset that lands where the mark already is still counts: the owner asked for a fresh findings key.
+    const stays = through >= mark.throughId;
+    const [last] = !stays && through > 0 ? await store.mail.emailsBefore(account.id, through + 1, 1) : [];
     const next = {
-        throughId: through,
-        throughAt: at,
+        throughId: stays ? mark.throughId : through,
+        throughAt: stays ? mark.throughAt : last?.id === through ? last.at : null,
         held: mark.held.filter((id) => id <= through),
         suspicious: mark.suspicious.filter((id) => id <= through),
         read: mark.read,

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

@@ -65,6 +65,7 @@ export interface FindingsReceipt {
 }
 export declare const findingText: (value: unknown, limit: number) => string;
 export declare const findingHash: (value: unknown) => string;
+export declare const snakeCase: (key: string) => string;
 /**
  * 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.
@@ -73,6 +74,8 @@ export declare const findingFields: (value: object, allowed: string[], noun: str
     id?: unknown;
     kind?: unknown;
 }) => void;
+/** Refuses a finding that leaves out a field `needed` lists, naming each one missing and all it needs. */
+export declare const findingNeeds: (value: Record<string, unknown>, needed: readonly string[], noun: string) => void;
 /** What differs between findings kinds: their wording and what one cited reference must look like. */
 export interface FindingsRules {
     /** "meeting findings" */
@@ -96,7 +99,7 @@ export declare const findingId: (raw: unknown, ids: Set<string>) => string;
 /** One fact, payment or task finding, its ID added to `ids`. */
 export declare const validateFinding: (finding: Finding, rules: FindingsRules, ids: Set<string>) => Finding;
 /** A date's or assignee's support: references the finding's own evidence cites. */
-export declare const support: (value: unknown, evidence: readonly FindingEvidence[]) => string[];
+export declare const support: (value: unknown, evidence: readonly FindingEvidence[], field: string) => string[];
 /** A batch's envelope — schema version, key, extractor — around 1–`most` findings each `one` checks. */
 export declare const validateBatch: <F>(input: {
     schemaVersion: 1;

package/dist/meetings/findings-rules.js

@@ -12,7 +12,15 @@ export const findingText = (value, limit) => {
     return value.trim();
 };
 export const findingHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+export const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+const findingWhere = (of) => {
+    const id = typeof of.id === "string" ? of.id : null;
+    const kind = typeof of.kind === "string" ? of.kind : null;
+    return {
+        where: id || kind ? ` in ${[id, kind && `(${kind})`].filter(Boolean).join(" ")}` : "",
+        named: { ...(id ? { finding: id } : {}), ...(kind ? { kind } : {}) },
+    };
+};
 /**
  * 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.
@@ -23,16 +31,18 @@ export const findingFields = (value, allowed, noun, of = value) => {
         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 { where, named } = findingWhere(of);
+    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, ...named });
+};
+/** Refuses a finding that leaves out a field `needed` lists, naming each one missing and all it needs. */
+export const findingNeeds = (value, needed, noun) => {
+    const missing = needed.filter((key) => value[key] === undefined);
+    if (!missing.length)
+        return;
+    const fields = missing.map(snakeCase);
+    const needs = needed.map(snakeCase);
+    const { where, named } = findingWhere(value);
+    throw new CliError("validation_error", `missing ${noun} field${fields.length > 1 ? "s" : ""} ${fields.join(", ")}${where}; it needs ${needs.join(", ")}`, { reason: "finding.missing-field", fields, needs, ...named });
 };
 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. */
@@ -130,9 +140,12 @@ export const validateFinding = (finding, rules, ids) => {
         return invalid("a task finding type is bug, chore or feature");
     if (!["explicit", "inferred"].includes(finding.commitment))
         return invalid("task commitment must be explicit or inferred");
-    if ((finding.dueAt === undefined) !== (finding.dueEvidence === undefined) ||
-        (finding.assignee === undefined) !== (finding.assigneeEvidence === undefined))
-        return invalid("optional dates and assignees require their supporting evidence");
+    if ((finding.dueAt === undefined) !== (finding.dueEvidence === undefined))
+        return invalid(`due_at comes with due_evidence: the ${rules.cited} references of this finding's evidence that give the date, ` +
+            `as a list of strings such as ["<reference>"]`);
+    if ((finding.assignee === undefined) !== (finding.assigneeEvidence === undefined))
+        return invalid(`assignee comes with assignee_evidence: the ${rules.cited} references of this finding's evidence that name ` +
+            `them, as a list of strings such as ["<reference>"]`);
     if (finding.assignee !== undefined &&
         (typeof finding.assignee !== "string" || !/^person:[1-9]\d*$/.test(finding.assignee)))
         return invalid("an assignee must be a person reference");
@@ -146,21 +159,25 @@ export const validateFinding = (finding, rules, ids) => {
         ...(finding.dueAt === undefined
             ? {}
             : {
-                dueAt: meetingTimestamp(finding.dueAt, "finding due date"),
-                dueEvidence: support(finding.dueEvidence, evidence),
+                dueAt: meetingTimestamp(finding.dueAt, "a task's due_at"),
+                dueEvidence: support(finding.dueEvidence, evidence, "due_evidence"),
             }),
         ...(finding.assignee === undefined
             ? {}
-            : { assignee: finding.assignee, assigneeEvidence: support(finding.assigneeEvidence, evidence) }),
+            : {
+                assignee: finding.assignee,
+                assigneeEvidence: support(finding.assigneeEvidence, evidence, "assignee_evidence"),
+            }),
     };
 };
 /** A date's or assignee's support: references the finding's own evidence cites. */
-export const support = (value, evidence) => {
+export const support = (value, evidence, field) => {
     if (!Array.isArray(value) ||
         value.length < 1 ||
         value.length > 8 ||
         value.some((ref) => typeof ref !== "string" || !evidence.some((item) => item.reference === ref)))
-        return invalid("date and assignee support must cite the finding's evidence");
+        return invalid(`${field} lists 1–8 references this finding's evidence cites, as plain strings such as ["<reference>"], ` +
+            "not evidence objects");
     return [...new Set(value)].sort();
 };
 /** A batch's envelope — schema version, key, extractor — around 1–`most` findings each `one` checks. */

package/dist/meetings/index.d.ts

@@ -9,7 +9,7 @@ export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, type MeetingExport, type MeetingExportFormat, type MeetingExportOptions, serializeVtt, } from "./export.js";
 export { type FindingEvidence, type FindingOutcome, findingHash, MEETING_FINDINGS_KIND, type MeetingFactFinding, type MeetingFinding, type MeetingFindingsInput, type MeetingFindingsReceipt, type MeetingTaskFinding, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
-export { type FactFinding, type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFields, findingFingerprint, findingId, findingText, type PaymentFinding, type TaskFinding, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
+export { type FactFinding, type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFields, findingFingerprint, findingId, findingNeeds, findingText, type PaymentFinding, snakeCase, type TaskFinding, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { type ImportFile, importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, type MeetingIssue, type MeetingItem, type MeetingOwner, meeting, meetingIssuesOf, meetingItem, } from "./item.js";

package/dist/meetings/index.js

@@ -6,7 +6,7 @@ export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, serializeVtt, } from "./export.js";
 export { findingHash, MEETING_FINDINGS_KIND, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
-export { findingFields, findingFingerprint, findingId, findingText, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
+export { findingFields, findingFingerprint, findingId, findingNeeds, findingText, snakeCase, validateBatch, validateFinding, validateFindings, validEvidence, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, meeting, meetingIssuesOf, meetingItem, } from "./item.js";

package/dist/meetings/timestamp.js

@@ -3,7 +3,7 @@ export const meetingTimestamp = (value, name) => {
     if (typeof value !== "string" ||
         !/^\d{4}-\d{2}-\d{2}T.+(?:Z|[+-]\d{2}:\d{2})$/i.test(value) ||
         !Number.isFinite(Date.parse(value)))
-        throw new CliError("validation_error", `${name} must be an ISO timestamp with a timezone`);
+        throw new CliError("validation_error", `${name} must be an ISO timestamp with a timezone, such as 2026-11-09T09:00:00Z`);
     const date = value.slice(0, 10);
     const instant = Date.parse(`${date}T00:00:00Z`);
     if (!Number.isFinite(instant) || new Date(instant).toISOString().slice(0, 10) !== date)

package/dist/services/index.d.ts

@@ -188,7 +188,7 @@ export { type PackageUpgradeOutcome, type PackageUpgradePorts, type PackageUpgra
 export { type PersonMeetingContext, type PersonMeetingContextItem, type PersonMeetingContextOptions, type PersonMeetingReadStore, personMeetingContext, } from "./person-meeting-context.js";
 export { privatePeopleService } from "./private-people.js";
 export { approveAsTask, type ProposalTaskStore, proposalSource } from "./proposal-tasks.js";
-export { type Decided, type Decision, emptyProposalRegistry, FACT_SUMMARIES, ORGANIZATION_ADD_KIND, type OrganizationProposal, type ProposalFilter, type ProposalKind, type ProposalRegistry, type ProposalRow, parseProposalIds, proposalRegistry, proposeOrganization, } from "./proposals/index.js";
+export { type Decided, type Decision, emptyProposalRegistry, FACT_SUMMARIES, ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND, type OrganizationProposal, type OrganizationRenameProposal, type ProposalFilter, type ProposalKind, type ProposalRegistry, type ProposalRow, parseProposalIds, proposalRegistry, proposeOrganization, proposeOrganizationRename, } from "./proposals/index.js";
 export type { RetentionQuery, RetentionService } from "./retention.js";
 export { retentionService } from "./retention.js";
 export { RESOURCES_SEARCHED, type SearchAllFound, type SearchAllItem, type SearchAllMessenger, type SearchAllRequest, type SearchedResource, searchAll, } from "./search-all.js";

package/dist/services/index.js

@@ -146,7 +146,7 @@ export { upgradePackage, } from "./package-upgrade.js";
 export { personMeetingContext, } from "./person-meeting-context.js";
 export { privatePeopleService } from "./private-people.js";
 export { approveAsTask, proposalSource } from "./proposal-tasks.js";
-export { emptyProposalRegistry, FACT_SUMMARIES, ORGANIZATION_ADD_KIND, parseProposalIds, proposalRegistry, proposeOrganization, } from "./proposals/index.js";
+export { emptyProposalRegistry, FACT_SUMMARIES, ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND, parseProposalIds, proposalRegistry, proposeOrganization, proposeOrganizationRename, } from "./proposals/index.js";
 export { retentionService } from "./retention.js";
 export { RESOURCES_SEARCHED, searchAll, } from "./search-all.js";
 export { RESOURCES_SEARCHED_WITH_MEETINGS, searchAllIncludingMeetings, searchAllWithMeetings, } from "./search-all-meetings.js";

package/dist/services/proposals/index.d.ts

@@ -1,5 +1,5 @@
 export { parseProposalIds } from "./ids.js";
 export { FACT_SUMMARIES } from "./kinds/findings.js";
-export { ORGANIZATION_ADD_KIND, type OrganizationProposal, proposeOrganization } from "./kinds/organization.js";
+export { ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND, type OrganizationProposal, type OrganizationRenameProposal, proposeOrganization, proposeOrganizationRename, } from "./kinds/organization.js";
 export { emptyProposalRegistry, proposalRegistry } from "./registry.js";
 export type { Decided, Decision, ProposalFilter, ProposalKind, ProposalRegistry, ProposalRow } from "./types.js";

package/dist/services/proposals/index.js

@@ -1,4 +1,4 @@
 export { parseProposalIds } from "./ids.js";
 export { FACT_SUMMARIES } from "./kinds/findings.js";
-export { ORGANIZATION_ADD_KIND, proposeOrganization } from "./kinds/organization.js";
+export { ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND, proposeOrganization, proposeOrganizationRename, } from "./kinds/organization.js";
 export { emptyProposalRegistry, proposalRegistry } from "./registry.js";

package/dist/services/proposals/kinds/organization.d.ts

@@ -1,11 +1,18 @@
 import type { Author, MessageStore, Organization, ProposedAction } from "../../../store/index.js";
 import type { ProposalKind } from "../types.js";
 export declare const ORGANIZATION_ADD_KIND = "organization_add";
+export declare const ORGANIZATION_RENAME_KIND = "organization_rename";
 export interface OrganizationProposal {
     name: string;
     kind: Organization["kind"];
     scope?: Organization["scope"];
 }
+export interface OrganizationRenameProposal {
+    organization: string;
+    name: string;
+}
 /** An agent's new organization waits as a stored proposal; the organization exists only once it is confirmed. */
 export declare const proposeOrganization: (store: Pick<MessageStore, "proposedActions">, input: OrganizationProposal, by: Author, reason?: string) => Promise<ProposedAction>;
+/** An agent's rename waits as a stored proposal too; the organization keeps its name until it is confirmed. */
+export declare const proposeOrganizationRename: (store: Pick<MessageStore, "proposedActions">, input: OrganizationRenameProposal, by: Author, reason?: string) => Promise<ProposedAction>;
 export declare const organizationKind: (store: Pick<MessageStore, "proposedActions" | "knowledge">) => ProposalKind;

package/dist/services/proposals/kinds/organization.js

@@ -1,16 +1,19 @@
 import { proposerOfAction } from "../../../store/index.js";
 import { actionStatus, kept, pushed, storedStatus } from "./shared.js";
 export const ORGANIZATION_ADD_KIND = "organization_add";
+export const ORGANIZATION_RENAME_KIND = "organization_rename";
 const rowOf = (action) => {
+    const renamed = action.kind === ORGANIZATION_RENAME_KIND;
     const { name, kind } = action.payload;
+    const { organization } = action.payload;
     return {
         id: action.id,
         kind: "organization",
         status: actionStatus(action.status),
         project: null,
-        subject: `organization:new`,
+        subject: renamed ? organization : "organization:new",
         object: null,
-        summary: `add ${kind} ${name}`,
+        summary: renamed ? `rename ${organization} to ${name}` : `add ${kind} ${name}`,
         proposedBy: proposerOfAction(action),
         reason: action.reason,
         evidence: [],
@@ -27,13 +30,20 @@ export const proposeOrganization = (store, input, by, reason) => store.proposedA
     payload: input,
     ...(reason === undefined ? {} : { reason }),
 });
+/** An agent's rename waits as a stored proposal too; the organization keeps its name until it is confirmed. */
+export const proposeOrganizationRename = (store, input, by, reason) => store.proposedActions.propose({
+    kind: ORGANIZATION_RENAME_KIND,
+    by,
+    payload: input,
+    ...(reason === undefined ? {} : { reason }),
+});
 export const organizationKind = (store) => ({
     kind: "organization",
-    stored: [ORGANIZATION_ADD_KIND],
+    stored: [ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND],
     list: async (filter) => {
         const status = storedStatus(filter);
         const actions = await store.proposedActions.list({
-            kinds: [ORGANIZATION_ADD_KIND],
+            kinds: [ORGANIZATION_ADD_KIND, ORGANIZATION_RENAME_KIND],
             ...(status === undefined ? {} : { status }),
             ...pushed(filter),
         });
@@ -45,7 +55,14 @@ export const organizationKind = (store) => ({
             await store.proposedActions.reject(id, by, reason);
             return { id, kind: "organization", status: "rejected", made: [] };
         }
-        const { name, kind, scope } = (await store.proposedActions.get(id)).payload;
+        const action = await store.proposedActions.get(id);
+        if (action.kind === ORGANIZATION_RENAME_KIND) {
+            const { organization, name } = action.payload;
+            const renamed = await store.knowledge.updateOrganization(organization, { name });
+            await store.proposedActions.approve(id, by, { organization: renamed.ref });
+            return { id, kind: "organization", status: "confirmed", made: [] };
+        }
+        const { name, kind, scope } = action.payload;
         const made = await store.knowledge.addOrganization({ name, kind, ...(scope === undefined ? {} : { scope }) });
         await store.proposedActions.approve(id, by, { organization: made.ref });
         return { id, kind: "organization", status: "confirmed", made: [made.ref] };

package/dist/store/knowledge-query.js

@@ -6,7 +6,13 @@ export const ORGANIZATIONS_QUERY = {
     backend: "sql",
     fields: queryFieldsOf(organization, {
         native: ["id", "kind", "scope", "created_at"],
-        examples: { id: "id:1", kind: "kind:company", scope: "scope:work", created_at: "created_at>=2026-01-01" },
+        examples: {
+            id: "id:1",
+            kind: "kind:company",
+            name: "name:*acme*",
+            scope: "scope:work",
+            created_at: "created_at>=2026-01-01",
+        },
     }),
 };
 export const PROJECTS_QUERY = {

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

@@ -159,6 +159,8 @@ export interface FinanceStore {
         /** Issued or partly paid. */
         open?: boolean;
         counterparty?: string;
+        /** The number printed on it, exactly. */
+        number?: string;
     }): Promise<Invoice[]>;
     /** The owner sends a draft: its status then follows its allocations. */
     issueInvoice(reference: string, by: Author): Promise<InvoiceDetail>;

package/dist/store/sqlite/finance.js

@@ -402,10 +402,10 @@ export const financeOperationsOver = (context) => {
             return database
                 .prepare(`${INVOICES} WHERE i.deleted_at IS NULL AND (? IS NULL OR i.direction = ?) AND (? IS NULL OR i.status = ?) ` +
                 "AND (? IS NULL OR i.review = ?) AND (? IS NULL OR i.project_id = ?) " +
-                "AND (? IS NULL OR (i.counterparty_type = ? AND i.counterparty_id = ?)) " +
+                "AND (? IS NULL OR (i.counterparty_type = ? AND i.counterparty_id = ?)) AND (? IS NULL OR i.number = ?) " +
                 `${filter.open ? "AND i.status IN ('issued', 'partly_paid') " : ""}AND ${by.sql} ` +
                 "ORDER BY i.created_at DESC, i.id DESC LIMIT ?")
-                .all(filter.direction ?? null, filter.direction ?? null, status, status, review, review, project, project, counterparty?.type ?? null, counterparty?.type ?? null, counterparty?.id ?? null, ...by.params, limitOf(filter.limit))
+                .all(filter.direction ?? null, filter.direction ?? null, status, status, review, review, project, project, counterparty?.type ?? null, counterparty?.type ?? null, counterparty?.id ?? null, filter.number ?? null, filter.number ?? null, ...by.params, limitOf(filter.limit))
                 .map(invoiceOf);
         },
         issueInvoice: (reference, by) => {