@wirecat/cli-core 0.558.0 → 0.559.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ shape of this file.
 
 ## Unreleased
 
+## 0.559.0 — 02.11.2026
+
+### Added
+
+- **Imports through one envelope (store version 47).** `ingest(store, envelope, { account, dryRun })` in
+  `./services` takes the v1 records envelope (`schema_version`, `source { provider, account, batch_id }`, `records[]`
+  with `key`, `type`, `external_id`, `operation` `upsert` or `delete`, `fields`, `revision`, `relations[]`), or a JSONL
+  file through `envelopeOfJsonl`. Its JSON Schema (Draft 2020-12) is `RECORDS_ENVELOPE_SCHEMA` and
+  `@wirecat/cli-core/schemas/records-envelope.v1.schema.json`. Each record is kept in the new `records` table, unique
+  per account, type and external id: the same import twice writes nothing, a lower revision is refused, a delete is
+  soft, and a field that looks like a secret is refused. The receipt counts created, updated, unchanged, deleted and
+  refused records, and each error carries a JSON pointer and a stable code.
+- **An import never writes confirmed money.** An `invoice` or `payment` record becomes a proposal by the bot `import`,
+  decided in the proposal inbox. A reference to a record not yet imported waits for it, and a person or organization
+  record is linked only by the owner (`store.records.map`), never by name. `store.records` lists and reads records,
+  waiting and flagged ones too.
+
 ## 0.558.0 — 02.11.2026
 
 ### Changed — may break callers

package/dist/domain/records.d.ts

@@ -0,0 +1,161 @@
+export declare const RECORDS_SCHEMA_VERSION = 1;
+export declare const RECORD_OPERATIONS: readonly ["upsert", "delete"];
+/** Types with a table of their own; anything else a source sends is `custom:<name>` and stays a record only. */
+export declare const RECORD_ENTITY_TYPES: readonly ["invoice", "payment", "person", "organization", "project"];
+export type RecordOperation = (typeof RECORD_OPERATIONS)[number];
+export type RecordEntityType = (typeof RECORD_ENTITY_TYPES)[number];
+export interface RecordRelation {
+    /** What the target is to this record: `counterparty`, `payer`, `settles`, or a source's own word. */
+    role: string;
+    type: string;
+    external_id: string;
+}
+export interface EnvelopeRecord {
+    /** The caller's name for this line, unique in the envelope; the receipt cites it. */
+    key: string;
+    type: string;
+    external_id: string;
+    operation: RecordOperation;
+    fields?: Record<string, unknown>;
+    /** Goes up with each change at the source; a lower one than the store holds is refused. */
+    revision?: number;
+    relations?: RecordRelation[];
+}
+export interface EnvelopeSource {
+    provider: string;
+    account: string;
+    batch_id: string;
+}
+export interface RecordsEnvelope {
+    schema_version: 1;
+    source: EnvelopeSource;
+    records: EnvelopeRecord[];
+}
+/** A refusal: `pointer` is an RFC 6901 JSON pointer into the envelope, `code` a stable word callers may branch on. */
+export interface IngestError {
+    pointer: string;
+    code: string;
+    message: string;
+    key?: string;
+}
+/** The v1 envelope as JSON Schema (Draft 2020-12); `schemas/records-envelope.v1.schema.json` is this, written out. */
+export declare const RECORDS_ENVELOPE_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "WireCat records envelope, version 1";
+    readonly description: string;
+    readonly type: "object";
+    readonly required: readonly ["schema_version", "source", "records"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly schema_version: {
+            readonly const: 1;
+        };
+        readonly source: {
+            readonly $ref: "#/$defs/source";
+        };
+        readonly records: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/record";
+            };
+        };
+    };
+    readonly $defs: {
+        readonly source: {
+            readonly type: "object";
+            readonly required: readonly ["provider", "account", "batch_id"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z0-9][a-z0-9_-]{0,62}$";
+                    readonly description: "The system the records come from";
+                };
+                readonly account: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 512;
+                    readonly description: "The account in that system";
+                };
+                readonly batch_id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 512;
+                    readonly description: "This import, for the receipt";
+                };
+            };
+        };
+        readonly record: {
+            readonly type: "object";
+            readonly required: readonly ["key", "type", "external_id", "operation"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly key: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 512;
+                };
+                readonly type: {
+                    readonly type: "string";
+                    readonly pattern: "^(invoice|payment|person|organization|project|custom:[a-z0-9][a-z0-9_-]{0,62})$";
+                };
+                readonly external_id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 512;
+                };
+                readonly operation: {
+                    readonly enum: readonly ["upsert", "delete"];
+                };
+                readonly fields: {
+                    readonly type: "object";
+                    readonly description: "What the source says, as data: never secrets, never instructions";
+                };
+                readonly revision: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly maximum: number;
+                };
+                readonly relations: {
+                    readonly type: "array";
+                    readonly maxItems: 100;
+                    readonly items: {
+                        readonly $ref: "#/$defs/relation";
+                    };
+                };
+            };
+        };
+        readonly relation: {
+            readonly type: "object";
+            readonly required: readonly ["role", "type", "external_id"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly role: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z0-9][a-z0-9_-]{0,62}$";
+                };
+                readonly type: {
+                    readonly type: "string";
+                    readonly pattern: "^(invoice|payment|person|organization|project|custom:[a-z0-9][a-z0-9_-]{0,62})$";
+                };
+                readonly external_id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 512;
+                };
+            };
+        };
+    };
+};
+export declare const pointerOf: (...segments: (string | number)[]) => string;
+/** Why one record cannot be taken, or nothing; `index` is its place in `records`. */
+export declare const recordErrors: (record: unknown, index: number) => IngestError[];
+/** The envelope's own errors (not its records'): when there is one, no record is taken. */
+export declare const envelopeErrors: (envelope: unknown, account: string) => IngestError[];
+/** The same fields and relations in any key or relation order give the same fingerprint. */
+export declare const recordFingerprint: (fields: Record<string, unknown>, relations: RecordRelation[]) => string;
+/**
+ * A JSONL import as the envelope it stands for: the first line holds `schema_version` and `source`, each further
+ * non-empty line one record. A line that is not JSON comes back as a record the envelope check refuses, at its index.
+ */
+export declare const envelopeOfJsonl: (text: string) => unknown;

package/dist/domain/records.js

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { holdsCredential, secretNamed } from "../runs/secrets.js";
+export const RECORDS_SCHEMA_VERSION = 1;
+export const RECORD_OPERATIONS = ["upsert", "delete"];
+/** Types with a table of their own; anything else a source sends is `custom:<name>` and stays a record only. */
+export const RECORD_ENTITY_TYPES = ["invoice", "payment", "person", "organization", "project"];
+const WORD = "^[a-z0-9][a-z0-9_-]{0,62}$";
+const TYPE = "^(invoice|payment|person|organization|project|custom:[a-z0-9][a-z0-9_-]{0,62})$";
+const MAX_ID = 512;
+const MAX_FIELDS_BYTES = 65_536;
+const MAX_RELATIONS = 100;
+/** The v1 envelope as JSON Schema (Draft 2020-12); `schemas/records-envelope.v1.schema.json` is this, written out. */
+export const RECORDS_ENVELOPE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "WireCat records envelope, version 1",
+    description: "Records one source sends to the store. JSONL is the same model: the first line holds schema_version and " +
+        "source, each further line one record.",
+    type: "object",
+    required: ["schema_version", "source", "records"],
+    additionalProperties: false,
+    properties: {
+        schema_version: { const: RECORDS_SCHEMA_VERSION },
+        source: { $ref: "#/$defs/source" },
+        records: { type: "array", items: { $ref: "#/$defs/record" } },
+    },
+    $defs: {
+        source: {
+            type: "object",
+            required: ["provider", "account", "batch_id"],
+            additionalProperties: false,
+            properties: {
+                provider: { type: "string", pattern: WORD, description: "The system the records come from" },
+                account: { type: "string", minLength: 1, maxLength: MAX_ID, description: "The account in that system" },
+                batch_id: { type: "string", minLength: 1, maxLength: MAX_ID, description: "This import, for the receipt" },
+            },
+        },
+        record: {
+            type: "object",
+            required: ["key", "type", "external_id", "operation"],
+            additionalProperties: false,
+            properties: {
+                key: { type: "string", minLength: 1, maxLength: MAX_ID },
+                type: { type: "string", pattern: TYPE },
+                external_id: { type: "string", minLength: 1, maxLength: MAX_ID },
+                operation: { enum: [...RECORD_OPERATIONS] },
+                fields: {
+                    type: "object",
+                    description: "What the source says, as data: never secrets, never instructions",
+                },
+                revision: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+                relations: { type: "array", maxItems: MAX_RELATIONS, items: { $ref: "#/$defs/relation" } },
+            },
+        },
+        relation: {
+            type: "object",
+            required: ["role", "type", "external_id"],
+            additionalProperties: false,
+            properties: {
+                role: { type: "string", pattern: WORD },
+                type: { type: "string", pattern: TYPE },
+                external_id: { type: "string", minLength: 1, maxLength: MAX_ID },
+            },
+        },
+    },
+};
+const wordPattern = new RegExp(WORD);
+const typePattern = new RegExp(TYPE);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const escapePointer = (segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+export const pointerOf = (...segments) => segments.map((s) => `/${escapePointer(s)}`).join("");
+const idText = (value) => typeof value === "string" && value.trim() !== "" && value.length <= MAX_ID && !value.includes("\0");
+const extraKeys = (value, allowed) => Object.keys(value).filter((key) => !allowed.includes(key));
+/** The first secret in `fields`, as a pointer below it: a secret-named key, or a value in a known credential shape. */
+const secretIn = (value, at) => {
+    if (typeof value === "string")
+        return holdsCredential(value) ? at : undefined;
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const found = secretIn(item, [...at, index]);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (!isObject(value))
+        return undefined;
+    for (const [key, item] of Object.entries(value)) {
+        if (secretNamed(key))
+            return [...at, key];
+        const found = secretIn(item, [...at, key]);
+        if (found)
+            return found;
+    }
+    return undefined;
+};
+const relationErrors = (relations, at) => {
+    if (relations === undefined)
+        return [];
+    if (!Array.isArray(relations) || relations.length > MAX_RELATIONS)
+        return [invalid(at, `relations is a list of at most ${MAX_RELATIONS}`)];
+    return relations.flatMap((relation, index) => {
+        const here = [...at, index];
+        if (!isObject(relation))
+            return [invalid(here, "a relation is an object")];
+        const extra = extraKeys(relation, ["role", "type", "external_id"]);
+        if (extra.length > 0)
+            return [invalid([...here, extra[0]], "a relation holds role, type and external_id")];
+        if (typeof relation.role !== "string" || !wordPattern.test(relation.role))
+            return [invalid([...here, "role"], "a role is lowercase letters, digits, - and _")];
+        if (typeof relation.type !== "string" || !typePattern.test(relation.type))
+            return [invalid([...here, "type"], `a type is one of ${RECORD_ENTITY_TYPES.join(", ")} or custom:<name>`)];
+        if (!idText(relation.external_id))
+            return [invalid([...here, "external_id"], `an external id takes 1–${MAX_ID} characters`)];
+        return [];
+    });
+};
+const invalid = (at, message, code = "record.invalid") => ({
+    pointer: pointerOf(...at),
+    code,
+    message,
+});
+/** Why one record cannot be taken, or nothing; `index` is its place in `records`. */
+export const recordErrors = (record, index) => {
+    const at = ["records", index];
+    if (!isObject(record))
+        return [invalid(at, "a record is an object")];
+    const key = typeof record.key === "string" ? record.key : undefined;
+    const withKey = (errors) => errors.map((error) => (key === undefined ? error : { ...error, key }));
+    const extra = extraKeys(record, ["key", "type", "external_id", "operation", "fields", "revision", "relations"]);
+    if (extra.length > 0)
+        return withKey([invalid([...at, extra[0]], `a record has no ${extra[0]}`)]);
+    if (!idText(record.key))
+        return [invalid([...at, "key"], `a key takes 1–${MAX_ID} characters`)];
+    if (typeof record.type !== "string" || !typePattern.test(record.type))
+        return withKey([
+            invalid([...at, "type"], `a type is one of ${RECORD_ENTITY_TYPES.join(", ")} or custom:<name>`, "record.type"),
+        ]);
+    if (!idText(record.external_id))
+        return withKey([invalid([...at, "external_id"], `an external id takes 1–${MAX_ID} characters`)]);
+    if (!RECORD_OPERATIONS.includes(record.operation))
+        return withKey([invalid([...at, "operation"], "an operation is upsert or delete")]);
+    if (record.revision !== undefined &&
+        (typeof record.revision !== "number" || !Number.isSafeInteger(record.revision) || record.revision < 0))
+        return withKey([invalid([...at, "revision"], "a revision is a whole number, 0 or more")]);
+    if (record.operation === "upsert" && !isObject(record.fields))
+        return withKey([invalid([...at, "fields"], "an upsert carries its fields as an object")]);
+    if (record.fields !== undefined && !isObject(record.fields))
+        return withKey([invalid([...at, "fields"], "fields is an object")]);
+    if (record.fields !== undefined && Buffer.byteLength(JSON.stringify(record.fields)) > MAX_FIELDS_BYTES)
+        return withKey([invalid([...at, "fields"], `fields take at most ${MAX_FIELDS_BYTES} bytes`, "record.too-large")]);
+    const secret = record.fields === undefined ? undefined : secretIn(record.fields, [...at, "fields"]);
+    if (secret)
+        return withKey([
+            invalid(secret, "a secret never goes into the store: drop this field at the source", "record.secret-field"),
+        ]);
+    return withKey(relationErrors(record.relations, [...at, "relations"]));
+};
+/** The envelope's own errors (not its records'): when there is one, no record is taken. */
+export const envelopeErrors = (envelope, account) => {
+    if (!isObject(envelope))
+        return [invalid([], "an envelope is an object", "envelope.invalid")];
+    const extra = extraKeys(envelope, ["schema_version", "source", "records"]);
+    if (extra.length > 0)
+        return [invalid([extra[0]], `an envelope has no ${extra[0]}`, "envelope.invalid")];
+    if (envelope.schema_version !== RECORDS_SCHEMA_VERSION)
+        return [
+            invalid(["schema_version"], `this build reads schema_version ${RECORDS_SCHEMA_VERSION}, not ${JSON.stringify(envelope.schema_version)}`, "envelope.schema-version"),
+        ];
+    const { source } = envelope;
+    if (!isObject(source))
+        return [invalid(["source"], "source is an object", "envelope.invalid")];
+    const sourceExtra = extraKeys(source, ["provider", "account", "batch_id"]);
+    if (sourceExtra.length > 0)
+        return [
+            invalid(["source", sourceExtra[0]], "source holds provider, account and batch_id", "envelope.invalid"),
+        ];
+    if (typeof source.provider !== "string" || !wordPattern.test(source.provider))
+        return [invalid(["source", "provider"], "a provider is lowercase letters, digits, - and _", "envelope.invalid")];
+    if (!idText(source.account))
+        return [invalid(["source", "account"], `an account takes 1–${MAX_ID} characters`, "envelope.invalid")];
+    if (!idText(source.batch_id))
+        return [invalid(["source", "batch_id"], `a batch id takes 1–${MAX_ID} characters`, "envelope.invalid")];
+    if (source.account !== account)
+        return [
+            invalid(["source", "account"], `the envelope is for account ${JSON.stringify(source.account)}, the import for ${JSON.stringify(account)}`, "envelope.account-mismatch"),
+        ];
+    if (!Array.isArray(envelope.records))
+        return [invalid(["records"], "records is a list", "envelope.invalid")];
+    return [];
+};
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, canonical(value[key])]));
+};
+/** The same fields and relations in any key or relation order give the same fingerprint. */
+export const recordFingerprint = (fields, relations) => createHash("sha256")
+    .update(JSON.stringify(canonical({
+    fields,
+    relations: relations
+        .map((relation) => [relation.role, relation.type, relation.external_id])
+        .sort((a, b) => a.join("\0").localeCompare(b.join("\0"))),
+})))
+    .digest("hex");
+/**
+ * A JSONL import as the envelope it stands for: the first line holds `schema_version` and `source`, each further
+ * non-empty line one record. A line that is not JSON comes back as a record the envelope check refuses, at its index.
+ */
+export const envelopeOfJsonl = (text) => {
+    const lines = text.split(/\r?\n/);
+    const first = lines.findIndex((line) => line.trim() !== "");
+    if (first < 0)
+        return {};
+    const parse = (line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return line;
+        }
+    };
+    const header = parse(lines[first]);
+    const records = [];
+    for (let at = first + 1; at < lines.length; at++) {
+        const line = lines[at];
+        if (line.trim() !== "")
+            records.push(parse(line));
+    }
+    return isObject(header) ? { ...header, records } : header;
+};

package/dist/errors/reasons.js

@@ -151,6 +151,15 @@ const OTHERS = [
     validation("finance.ref", "the reference names no invoice or payment"),
     validation("finance.status", "the invoice's status does not allow this"),
     validation("finance.total", "the invoice's total is not the sum of its lines"),
+    validation("record.entity", "the invoice or payment the record stands for was refused"),
+    ["record.map-owner-only", "permission_error", "only the owner says which entity a source record is"],
+    validation("record.map-type", "a record maps only to an entity of its own type"),
+    validation("record.mapped", "the record already stands for another entity"),
+    validation("record.not-found", "the store holds no such record to delete"),
+    validation("record.invalid", "a field of the record is not the kind the entity needs"),
+    validation("record.reference-not-found", "a reference in the record's fields is not in the store"),
+    validation("record.relation-ambiguous", "the record names more than one target for a role that takes one"),
+    validation("record.stale-revision", "the store holds a newer revision of the record"),
     validation("memory.evidence-required", "a memory needs its evidence"),
     validation("memory.scope-required", "a memory needs its scope"),
     validation("money.amount", "the amount is not a decimal string in the currency's scale"),

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/runs/secrets.d.ts

@@ -1,4 +1,6 @@
 export declare const secretNamed: (name: string) => boolean;
+/** A credential in a shape vendors publish so scanners find it: a known token prefix, a private key, a `Bearer` value. */
+export declare const holdsCredential: (text: string) => boolean;
 /**
  * Whether a run of token characters is a random string rather than words: long, mixed case, high Shannon entropy,
  * cut into short pieces (`Kz9vQ2mX`) where a name is cut into words (`InlineQueryResultMpeg4Gif`).

package/dist/runs/secrets.js

@@ -54,6 +54,8 @@ const PRIVATE_KEY = /-----BEGIN[A-Z ]* PRIVATE KEY-----[\s\S]*?(?:-----END[A-Z ]
 const SCHEME = /(?<![A-Za-z])(Bearer|Basic)(\s+)(?![A-Z]?[a-z]+(?![A-Za-z0-9]))[A-Za-z0-9._~+/=-]{8,}/g;
 // After a bare space only a value that is not a plain word: `pin 1234` is a secret, `pin this message` is not.
 const NAMED_PAIR = /(?<![\p{L}\p{N}])([\p{L}\p{N}_.-]*(?:token|pass|pwd|pin|otp|2fa|secret|credential|cookie|authorization|key|contrase|clave|пароль|пин|код)[\p{L}\p{N}_.-]*)(["']?\s*(?:=>|[:=])\s*["']?|\s+(?![\p{L}]+(?![\p{L}\p{N}])))((?:Bearer\s+|Basic\s+)?)([^\s"'&,;]+)/giu;
+/** A credential in a shape vendors publish so scanners find it: a known token prefix, a private key, a `Bearer` value. */
+export const holdsCredential = (text) => text.search(PRIVATE_KEY) >= 0 || text.search(KNOWN_TOKENS) >= 0 || text.search(SCHEME) >= 0;
 /**
  * Whether a run of token characters is a random string rather than words: long, mixed case, high Shannon entropy,
  * cut into short pieces (`Kz9vQ2mX`) where a name is cut into words (`InlineQueryResultMpeg4Gif`).

package/dist/services/index.d.ts

@@ -6,6 +6,7 @@ export { type ChatCoverage, chatCoverage } from "./chat-coverage.js";
 export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextEvidenceSender, ContextIndex, ContextReadLimits, ContextReadUsage, ContextRecordReader, ContextSource, ScopedContextEvidenceReader, } from "./context-evidence.js";
 export { contextEvidenceFingerprint, createContextEvidenceReader } from "./context-evidence.js";
 export { excerpt } from "./excerpt.js";
+export { type IngestOptions, type IngestReceipt, ingest } from "./ingest.js";
 export { aliasHits, chatSenders, chatTitle, combinedScore, DEFAULT_LIMIT as DEFAULT_LINK_SCAN_LIMIT, DEFAULT_THRESHOLD as DEFAULT_LINK_SCAN_THRESHOLD, emailDomain, type LinkCandidate, type LinkScorer, mailThread, memberChats, memberDialog, PERSON_SCORERS, PERSON_THRESHOLD as PERSON_LINK_SCAN_THRESHOLD, SCAN_BOT, SCORERS, type ScanInput as LinkScanInput, type ScannedProject, type ScannedProposal, type ScanResult as LinkScanResult, type ScorerInput, type Signal as LinkSignal, scanProjectLinks, } from "./link-scorers/index.js";
 export type { MediaArchiveOptions, MediaArchivePorts } from "./media-archive.js";
 export { archiveMedia, checkMediaArchive } from "./media-archive.js";

package/dist/services/index.js

@@ -5,6 +5,7 @@ export { AGENDA_DEFAULTS } from "./agenda.js";
 export { chatCoverage } from "./chat-coverage.js";
 export { contextEvidenceFingerprint, createContextEvidenceReader } from "./context-evidence.js";
 export { excerpt } from "./excerpt.js";
+export { ingest } from "./ingest.js";
 export { aliasHits, chatSenders, chatTitle, combinedScore, DEFAULT_LIMIT as DEFAULT_LINK_SCAN_LIMIT, DEFAULT_THRESHOLD as DEFAULT_LINK_SCAN_THRESHOLD, emailDomain, mailThread, memberChats, memberDialog, PERSON_SCORERS, PERSON_THRESHOLD as PERSON_LINK_SCAN_THRESHOLD, SCAN_BOT, SCORERS, scanProjectLinks, } from "./link-scorers/index.js";
 export { archiveMedia, checkMediaArchive } from "./media-archive.js";
 export { moveMediaArchive } from "./media-archive-move.js";

package/dist/services/ingest.d.ts

@@ -0,0 +1,45 @@
+import { type IngestError } from "../domain/records.js";
+import type { MessageStore } from "../store/store.js";
+export interface IngestOptions {
+    /** The account the caller means; the envelope's `source.account` must be this one. */
+    account: string;
+    /** Checks and plans everything, then writes nothing. */
+    dryRun?: boolean;
+    /** Records per transaction, 1000 by default. */
+    chunk?: number;
+}
+export interface IngestReceipt {
+    dryRun: boolean;
+    source: {
+        provider: string;
+        account: string;
+        batchId: string;
+    } | null;
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    refused: number;
+    /** `invoice:` and `payment:` proposals this import made; the owner confirms them in review. */
+    proposed: string[];
+    /** Kept, with no entity yet: each named role points at a record not imported, or one with no entity. */
+    waiting: {
+        key: string;
+        pointer: string;
+        missing: string[];
+    }[];
+    /** Changed or deleted at the source after the entity was made from it: the entity was not touched. */
+    flagged: {
+        key: string;
+        pointer: string;
+        entity: string;
+    }[];
+    errors: IngestError[];
+}
+/**
+ * Takes a v1 records envelope (or `envelopeOfJsonl` of a JSONL file) into the store: checks it, then writes per
+ * chunk in one transaction. The same import twice writes nothing new. A record with a lower revision than the stored
+ * one is refused, a delete is soft, a reference to a record not yet imported waits for it, and nothing is linked by
+ * name. An invoice or a payment becomes a proposal: an import never writes confirmed money.
+ */
+export declare const ingest: (store: Pick<MessageStore, "records">, envelope: unknown, { account, dryRun, chunk }: IngestOptions) => Promise<IngestReceipt>;

package/dist/services/ingest.js

@@ -0,0 +1,80 @@
+import { envelopeErrors, pointerOf, recordErrors, } from "../domain/records.js";
+const emptyReceipt = (dryRun) => ({
+    dryRun,
+    source: null,
+    created: 0,
+    updated: 0,
+    unchanged: 0,
+    deleted: 0,
+    refused: 0,
+    proposed: [],
+    waiting: [],
+    flagged: [],
+    errors: [],
+});
+/**
+ * Takes a v1 records envelope (or `envelopeOfJsonl` of a JSONL file) into the store: checks it, then writes per
+ * chunk in one transaction. The same import twice writes nothing new. A record with a lower revision than the stored
+ * one is refused, a delete is soft, a reference to a record not yet imported waits for it, and nothing is linked by
+ * name. An invoice or a payment becomes a proposal: an import never writes confirmed money.
+ */
+export const ingest = async (store, envelope, { account, dryRun = false, chunk = 1000 }) => {
+    const receipt = emptyReceipt(dryRun);
+    const broken = envelopeErrors(envelope, account);
+    if (broken.length > 0)
+        return { ...receipt, errors: broken };
+    const { source, records } = envelope;
+    receipt.source = { provider: source.provider, account: source.account, batchId: source.batch_id };
+    const taken = [];
+    const keys = new Set();
+    const identities = new Set();
+    for (const [index, record] of records.entries()) {
+        const errors = recordErrors(record, index);
+        const valid = record;
+        if (errors.length === 0 && keys.has(valid.key))
+            errors.push({
+                pointer: pointerOf("records", index, "key"),
+                code: "record.duplicate-key",
+                message: "another record of this envelope has this key",
+                key: valid.key,
+            });
+        const identity = errors.length === 0 ? `${valid.type}\0${valid.external_id}` : "";
+        if (errors.length === 0 && identities.has(identity))
+            errors.push({
+                pointer: pointerOf("records", index, "external_id"),
+                code: "record.duplicate",
+                message: `another record of this envelope is ${valid.type} ${valid.external_id}`,
+                key: valid.key,
+            });
+        if (errors.length > 0) {
+            receipt.refused += 1;
+            for (const error of errors)
+                receipt.errors.push(error);
+            continue;
+        }
+        keys.add(valid.key);
+        identities.add(identity);
+        taken.push({ index, record: valid });
+    }
+    const written = await store.records.write(source, taken, { dryRun, chunk });
+    for (const outcome of written.outcomes) {
+        receipt[outcome.status] += 1;
+        if (outcome.error)
+            receipt.errors.push(outcome.error);
+    }
+    for (const error of written.laterErrors)
+        receipt.errors.push(error);
+    receipt.errors.sort((a, b) => a.pointer.localeCompare(b.pointer, "en", { numeric: true }));
+    receipt.proposed = written.proposed;
+    receipt.waiting = written.waiting.map(({ index, key, missing }) => ({
+        key,
+        pointer: pointerOf("records", index, "relations"),
+        missing,
+    }));
+    receipt.flagged = written.flagged.map(({ index, key, entity }) => ({
+        key,
+        pointer: pointerOf("records", index),
+        entity,
+    }));
+    return receipt;
+};

package/dist/store/index.d.ts

@@ -54,6 +54,7 @@ export { type NearestNote, NOTE_FIELDS, type NoteChunkToEmbed, type NoteHit, typ
 export type { FileNoteInput, Link, LinkInput, LinkListFilter, Note, NoteFolder, NotesStore, NoteTag, } from "./sqlite/notes.js";
 export type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
 export { PROPOSAL_STATUSES, type ProposalInput, type ProposedAction, type ProposedActionsStore, proposerOfAction, } from "./sqlite/proposed-actions.js";
+export type { RecordKey, RecordOutcome, RecordStore, RecordsWritten, SourceRecord, } from "./sqlite/records.js";
 export type { LinkDecision, RelationUpdate } from "./sqlite/relation-proposals.js";
 export { fillSearchIndex, resetSearchIndex, type SearchIndexFill, type SearchIndexState, searchIndexState, } from "./sqlite/search-index.js";
 export type { SyncStateSave } from "./sqlite/sync.js";

package/dist/store/sqlite/accounts.js

@@ -114,6 +114,10 @@ export const purgeAccount = ({ orm, database }, accountKey) => {
     // The inbox project and its tasks are the owner's; only the tie to the account goes.
     orm.update(projects).set({ accountId: null }).where(eq(projects.accountId, accountKey)).run();
     orm.run(sql `DELETE FROM files WHERE account_id = ${accountKey}`);
+    // An entity made from a record is the owner's and stays; only what the source said goes.
+    const recordsOf = sql `(SELECT id FROM records WHERE account_id = ${accountKey})`;
+    orm.run(sql `DELETE FROM record_relations WHERE record_id IN ${recordsOf} OR target_id IN ${recordsOf}`);
+    orm.run(sql `DELETE FROM records WHERE account_id = ${accountKey}`);
     orm.delete(accounts).where(eq(accounts.id, accountKey)).run();
     dropOrphanPeople(database, unseenBefore);
     dropUnusedVectors(database, hashes);

package/dist/store/sqlite/manifest.js

@@ -62,6 +62,7 @@ export const MANIFEST = [
     { name: "20261102173102_version-45-finance", version: 45, minCompatible: 34 },
     { name: "20261102173113_version-45-finance-rules", version: 45, minCompatible: 34 },
     { name: "20261102185954_version-46-payment-facts", version: 46, minCompatible: 34 },
+    { name: "20261102192959_version-47-records", version: 47, minCompatible: 34 },
 ];
 export const generatedMigrations = (manifest = MANIFEST, generated = GENERATED) => {
     const migrations = [];