@aglyn/aglyn 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/data-transfer/match.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** How a key's values are made comparable. */
+export type MatchNormalizer = 'exact' | 'trim' | 'caseless' | 'email' | 'domain' | 'name' | 'slug' | 'phone' | 'externalId' | 'aglynId' | 'instant';
+/** One part of a compound match key: another field, and how its values compare. */
+export interface MatchKeyPart {
+    fieldId: string;
+    normalizer: MatchNormalizer;
+}
+/**
+ * One match key: a field, and how its values compare. With `with`, a
+ * compound key: a row carries it only when every part has a value, and a row
+ * and a record share it only when every part agrees — an event's title AND
+ * its start, so a weekly class is not one event. A compound key is named by
+ * its first field everywhere a key is named.
+ */
+export interface MatchKeySpec {
+    fieldId: string;
+    normalizer: MatchNormalizer;
+    with?: readonly MatchKeyPart[];
+}
+/** What joins the parts of a compound key's value: shown, and never inside a normalized part. */
+export declare const MATCH_KEY_PART_SEPARATOR = " \u241F ";
+/**
+ * The domain of a web address or email address: lowercased, `www.` and
+ * a trailing dot dropped, port and path ignored. `null` when there is none.
+ */
+export declare function domainOf(value: unknown): string | null;
+/** A name folded: accents, case, punctuation and spacing do not make a new name. */
+export declare function foldName(value: unknown): string;
+/** A slug folded: lowercase words joined by `-`. */
+export declare function foldSlug(value: unknown): string;
+/** A value under a normalizer, or `null` when it has no key (blank, unreadable). */
+export declare function normalizeMatchValue(normalizer: MatchNormalizer, value: unknown): string | null;
+/**
+ * A row's (or a record's) value under a key — every part normalized and
+ * joined for a compound key — or `null` when any part has none.
+ */
+export declare function matchKeyValue(key: MatchKeySpec, values: Readonly<Record<string, unknown>>): string | null;
+/** The key under which a lookup answer is filed. */
+export declare function matchLookupKey(fieldId: string, normalized: string): string;
+/** Field + normalized value → ids of the existing records holding it. */
+export type MatchLookup = ReadonlyMap<string, readonly string[]>;
+/** What the caller must look up: per key, the distinct normalized values the rows carry. */
+export interface MatchLookupRequest extends MatchKeySpec {
+    values: string[];
+}
+/** The values each key must be looked up for, distinct, in first-seen order. */
+export declare function matchLookupRequests(rows: readonly Readonly<Record<string, unknown>>[], keys: readonly MatchKeySpec[]): MatchLookupRequest[];
+/** Builds a {@link MatchLookup} from records: each record's values under every key. */
+export declare function buildMatchLookup(records: Iterable<{
+    id: string;
+    values: Readonly<Record<string, unknown>>;
+}>, keys: readonly MatchKeySpec[]): Map<string, string[]>;
+/** Which key found a row's record, and by what value. */
+export interface MatchedVia {
+    fieldId: string;
+    value: string;
+}
+/** What a row is about. */
+export type RowMatchOutcome = {
+    kind: 'new';
+} | {
+    kind: 'matched';
+    recordId: string;
+    via: MatchedVia;
+    /** Other records a lower-priority key pointed at — worth a warning. */
+    alsoMatched?: string[];
+} | {
+    kind: 'ambiguous';
+    recordIds: string[];
+    via: MatchedVia;
+} | {
+    kind: 'duplicateInFile';
+    firstRow: number;
+    via: MatchedVia;
+};
+/**
+ * One outcome per row (see the block header). A row is a duplicate when ANY
+ * key value it carries was carried by an earlier row; otherwise the keys
+ * are tried in order and the first that finds a record decides.
+ */
+export declare function matchRows(rows: readonly Readonly<Record<string, unknown>>[], keys: readonly MatchKeySpec[], lookup: MatchLookup): RowMatchOutcome[];
+/** How many rows had each outcome. */
+export declare function summarizeMatches(outcomes: readonly RowMatchOutcome[]): Record<RowMatchOutcome['kind'], number>;

package/src/lib/data-transfer/match.js

@@ -0,0 +1,244 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*==========================================
+ * RECORD MATCHING — which existing record each row of a file is about.
+ *
+ * The person picks match keys in priority order (the Aglyn id, an external
+ * id, an email, a domain, a name…). Each key is a field and a normalizer,
+ * so `Jane@Example.com ` and `jane@example.com` are one key and
+ * `https://www.example.com/about` and `bob@example.com` share a domain.
+ *
+ * Matching is pure: the caller asks storage for the records holding the
+ * requested key values ({@link matchLookupRequests}), hands the answer back
+ * as a {@link MatchLookup}, and gets one outcome per row:
+ *
+ *  - `new` — no key found a record;
+ *  - `matched` — the first key that found anything found exactly one;
+ *  - `ambiguous` — it found several, and the person must choose;
+ *  - `duplicateInFile` — an earlier row carries the same key value, so
+ *    both rows are about one record and the later one is held back.
+ *=========================================*/ import { normalizePhone } from "../foundation/definitions/contact.types.js";
+import { foldText } from "./similarity.js";
+/** What joins the parts of a compound key's value: shown, and never inside a normalized part. */ export const MATCH_KEY_PART_SEPARATOR = ' \u241f ';
+/**
+ * The domain of a web address or email address: lowercased, `www.` and
+ * a trailing dot dropped, port and path ignored. `null` when there is none.
+ */ export function domainOf(value) {
+    var _text_split_;
+    let text = String(value != null ? value : '').trim().toLowerCase();
+    if (!text) return null;
+    const at = text.lastIndexOf('@');
+    if (at >= 0 && !text.includes('://')) text = text.slice(at + 1);
+    text = text.replace(/^[a-z][a-z0-9+.-]*:\/\//, '').replace(/^[^@/]*@/, '');
+    text = ((_text_split_ = text.split(/[/?#]/)[0]) != null ? _text_split_ : '').replace(/:\d+$/, '').replace(/\.$/, '').replace(/^www\./, '');
+    return /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9-]{2,}$/.test(text) ? text : null;
+}
+/** A name folded: accents, case, punctuation and spacing do not make a new name. */ export function foldName(value) {
+    return foldText(value).replace(/&/g, ' and ').replace(/[^a-z0-9]+/g, ' ').trim();
+}
+/** A slug folded: lowercase words joined by `-`. */ export function foldSlug(value) {
+    return foldText(value).replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** A value under a normalizer, or `null` when it has no key (blank, unreadable). */ export function normalizeMatchValue(normalizer, value) {
+    if (value === null || value === undefined) return null;
+    const text = String(value);
+    let key;
+    switch(normalizer){
+        case 'exact':
+            key = text;
+            break;
+        case 'trim':
+        case 'externalId':
+        case 'aglynId':
+            key = text.trim();
+            break;
+        case 'caseless':
+            key = text.trim().toLowerCase();
+            break;
+        case 'email':
+            {
+                const lower = text.trim().toLowerCase();
+                key = /^[^\s@]+@[^\s@]+$/.test(lower) ? lower : null;
+                break;
+            }
+        case 'domain':
+            key = domainOf(text);
+            break;
+        case 'name':
+            key = foldName(text);
+            break;
+        case 'slug':
+            key = foldSlug(text);
+            break;
+        case 'phone':
+            key = normalizePhone(text);
+            break;
+        case 'instant':
+            key = instantOf(value);
+            break;
+    }
+    return key ? key.replaceAll(MATCH_KEY_PART_SEPARATOR, ' ') : null;
+}
+/**
+ * A moment to the minute, in UTC (`2026-10-05T14:30Z`), from epoch
+ * milliseconds, a `Date`, or any text `Date` reads; `null` when it is none.
+ * The file's ISO text and the record's stored milliseconds meet here.
+ */ function instantOf(value) {
+    const ms = typeof value === 'number' ? value : value instanceof Date ? value.getTime() : /^\d{11,}$/.test(String(value).trim()) ? Number(String(value).trim()) : Date.parse(String(value).trim());
+    if (!Number.isFinite(ms)) return null;
+    return `${new Date(ms).toISOString().slice(0, 16)}Z`;
+}
+/**
+ * A row's (or a record's) value under a key — every part normalized and
+ * joined for a compound key — or `null` when any part has none.
+ */ export function matchKeyValue(key, values) {
+    var _key_with;
+    const first = normalizeMatchValue(key.normalizer, values[key.fieldId]);
+    if (!first || !((_key_with = key.with) == null ? void 0 : _key_with.length)) return first;
+    const parts = [
+        first
+    ];
+    for (const part of key.with){
+        const value = normalizeMatchValue(part.normalizer, values[part.fieldId]);
+        if (!value) return null;
+        parts.push(value);
+    }
+    return parts.join(MATCH_KEY_PART_SEPARATOR);
+}
+/** The key under which a lookup answer is filed. */ export function matchLookupKey(fieldId, normalized) {
+    return `${fieldId}\u0000${normalized}`;
+}
+/** The values each key must be looked up for, distinct, in first-seen order. */ export function matchLookupRequests(rows, keys) {
+    return keys.map((key)=>{
+        const values = new Set();
+        for (const row of rows){
+            const normalized = matchKeyValue(key, row);
+            if (normalized) values.add(normalized);
+        }
+        return _extends({}, key, {
+            values: [
+                ...values
+            ]
+        });
+    });
+}
+/** Builds a {@link MatchLookup} from records: each record's values under every key. */ export function buildMatchLookup(records, keys) {
+    const lookup = new Map();
+    for (const record of records){
+        for (const key of keys){
+            const raw = key.normalizer === 'aglynId' && record.values[key.fieldId] === undefined ? record.id : record.values[key.fieldId];
+            const values = Array.isArray(raw) ? raw : [
+                raw
+            ];
+            for (const value of values){
+                var _lookup_get;
+                const normalized = matchKeyValue(key, _extends({}, record.values, {
+                    [key.fieldId]: value
+                }));
+                if (!normalized) continue;
+                const at = matchLookupKey(key.fieldId, normalized);
+                const ids = (_lookup_get = lookup.get(at)) != null ? _lookup_get : [];
+                if (!ids.includes(record.id)) ids.push(record.id);
+                lookup.set(at, ids);
+            }
+        }
+    }
+    return lookup;
+}
+/**
+ * One outcome per row (see the block header). A row is a duplicate when ANY
+ * key value it carries was carried by an earlier row; otherwise the keys
+ * are tried in order and the first that finds a record decides.
+ */ export function matchRows(rows, keys, lookup) {
+    const firstRowOf = new Map();
+    return rows.map((row, index)=>{
+        const carried = keys.map((key)=>({
+                key,
+                value: matchKeyValue(key, row)
+            })).filter((entry)=>Boolean(entry.value));
+        const duplicateOf = carried.map((entry)=>({
+                entry,
+                first: firstRowOf.get(matchLookupKey(entry.key.fieldId, entry.value))
+            })).find((found)=>found.first !== undefined);
+        for (const entry of carried){
+            const at = matchLookupKey(entry.key.fieldId, entry.value);
+            if (!firstRowOf.has(at)) firstRowOf.set(at, index);
+        }
+        if (duplicateOf) {
+            return {
+                kind: 'duplicateInFile',
+                firstRow: duplicateOf.first,
+                via: {
+                    fieldId: duplicateOf.entry.key.fieldId,
+                    value: duplicateOf.entry.value
+                }
+            };
+        }
+        for(let at = 0; at < carried.length; at += 1){
+            var _lookup_get;
+            const { key, value } = carried[at];
+            const ids = (_lookup_get = lookup.get(matchLookupKey(key.fieldId, value))) != null ? _lookup_get : [];
+            if (!ids.length) continue;
+            const via = {
+                fieldId: key.fieldId,
+                value
+            };
+            if (ids.length > 1) return {
+                kind: 'ambiguous',
+                recordIds: [
+                    ...ids
+                ],
+                via
+            };
+            const recordId = ids[0];
+            const others = new Set();
+            for (const later of carried.slice(at + 1)){
+                var _lookup_get1;
+                for (const id of (_lookup_get1 = lookup.get(matchLookupKey(later.key.fieldId, later.value))) != null ? _lookup_get1 : []){
+                    if (id !== recordId) others.add(id);
+                }
+            }
+            return others.size ? {
+                kind: 'matched',
+                recordId,
+                via,
+                alsoMatched: [
+                    ...others
+                ]
+            } : {
+                kind: 'matched',
+                recordId,
+                via
+            };
+        }
+        return {
+            kind: 'new'
+        };
+    });
+}
+/** How many rows had each outcome. */ export function summarizeMatches(outcomes) {
+    const summary = {
+        new: 0,
+        matched: 0,
+        ambiguous: 0,
+        duplicateInFile: 0
+    };
+    for (const outcome of outcomes)summary[outcome.kind] += 1;
+    return summary;
+}
+
+//# sourceMappingURL=match.js.map

package/src/lib/data-transfer/match.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/data-transfer/match.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * RECORD MATCHING — which existing record each row of a file is about.\n *\n * The person picks match keys in priority order (the Aglyn id, an external\n * id, an email, a domain, a name…). Each key is a field and a normalizer,\n * so `Jane@Example.com ` and `jane@example.com` are one key and\n * `https://www.example.com/about` and `bob@example.com` share a domain.\n *\n * Matching is pure: the caller asks storage for the records holding the\n * requested key values ({@link matchLookupRequests}), hands the answer back\n * as a {@link MatchLookup}, and gets one outcome per row:\n *\n *  - `new` — no key found a record;\n *  - `matched` — the first key that found anything found exactly one;\n *  - `ambiguous` — it found several, and the person must choose;\n *  - `duplicateInFile` — an earlier row carries the same key value, so\n *    both rows are about one record and the later one is held back.\n *=========================================*/\n\nimport { normalizePhone } from '../foundation/definitions/contact.types'\nimport { foldText } from './similarity'\n\n/** How a key's values are made comparable. */\nexport type MatchNormalizer =\n  | 'exact'\n  | 'trim'\n  | 'caseless'\n  | 'email'\n  | 'domain'\n  | 'name'\n  | 'slug'\n  | 'phone'\n  | 'externalId'\n  | 'aglynId'\n  | 'instant'\n\n/** One part of a compound match key: another field, and how its values compare. */\nexport interface MatchKeyPart {\n  fieldId: string\n  normalizer: MatchNormalizer\n}\n\n/**\n * One match key: a field, and how its values compare. With `with`, a\n * compound key: a row carries it only when every part has a value, and a row\n * and a record share it only when every part agrees — an event's title AND\n * its start, so a weekly class is not one event. A compound key is named by\n * its first field everywhere a key is named.\n */\nexport interface MatchKeySpec {\n  fieldId: string\n  normalizer: MatchNormalizer\n  with?: readonly MatchKeyPart[]\n}\n\n/** What joins the parts of a compound key's value: shown, and never inside a normalized part. */\nexport const MATCH_KEY_PART_SEPARATOR = ' \\u241f '\n\n/**\n * The domain of a web address or email address: lowercased, `www.` and\n * a trailing dot dropped, port and path ignored. `null` when there is none.\n */\nexport function domainOf(value: unknown): string | null {\n  let text = String(value ?? '').trim().toLowerCase()\n  if (!text) return null\n  const at = text.lastIndexOf('@')\n  if (at >= 0 && !text.includes('://')) text = text.slice(at + 1)\n  text = text.replace(/^[a-z][a-z0-9+.-]*:\\/\\//, '').replace(/^[^@/]*@/, '')\n  text = (text.split(/[/?#]/)[0] ?? '').replace(/:\\d+$/, '').replace(/\\.$/, '').replace(/^www\\./, '')\n  return /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9-]{2,}$/.test(text) ? text : null\n}\n\n/** A name folded: accents, case, punctuation and spacing do not make a new name. */\nexport function foldName(value: unknown): string {\n  return foldText(value)\n    .replace(/&/g, ' and ')\n    .replace(/[^a-z0-9]+/g, ' ')\n    .trim()\n}\n\n/** A slug folded: lowercase words joined by `-`. */\nexport function foldSlug(value: unknown): string {\n  return foldText(value)\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n}\n\n/** A value under a normalizer, or `null` when it has no key (blank, unreadable). */\nexport function normalizeMatchValue(normalizer: MatchNormalizer, value: unknown): string | null {\n  if (value === null || value === undefined) return null\n  const text = String(value)\n  let key: string | null\n  switch (normalizer) {\n    case 'exact':\n      key = text\n      break\n    case 'trim':\n    case 'externalId':\n    case 'aglynId':\n      key = text.trim()\n      break\n    case 'caseless':\n      key = text.trim().toLowerCase()\n      break\n    case 'email': {\n      const lower = text.trim().toLowerCase()\n      key = /^[^\\s@]+@[^\\s@]+$/.test(lower) ? lower : null\n      break\n    }\n    case 'domain':\n      key = domainOf(text)\n      break\n    case 'name':\n      key = foldName(text)\n      break\n    case 'slug':\n      key = foldSlug(text)\n      break\n    case 'phone':\n      key = normalizePhone(text)\n      break\n    case 'instant':\n      key = instantOf(value)\n      break\n  }\n  return key ? key.replaceAll(MATCH_KEY_PART_SEPARATOR, ' ') : null\n}\n\n/**\n * A moment to the minute, in UTC (`2026-10-05T14:30Z`), from epoch\n * milliseconds, a `Date`, or any text `Date` reads; `null` when it is none.\n * The file's ISO text and the record's stored milliseconds meet here.\n */\nfunction instantOf(value: unknown): string | null {\n  const ms =\n    typeof value === 'number'\n      ? value\n      : value instanceof Date\n        ? value.getTime()\n        : /^\\d{11,}$/.test(String(value).trim())\n          ? Number(String(value).trim())\n          : Date.parse(String(value).trim())\n  if (!Number.isFinite(ms)) return null\n  return `${new Date(ms).toISOString().slice(0, 16)}Z`\n}\n\n/**\n * A row's (or a record's) value under a key — every part normalized and\n * joined for a compound key — or `null` when any part has none.\n */\nexport function matchKeyValue(key: MatchKeySpec, values: Readonly<Record<string, unknown>>): string | null {\n  const first = normalizeMatchValue(key.normalizer, values[key.fieldId])\n  if (!first || !key.with?.length) return first\n  const parts = [first]\n  for (const part of key.with) {\n    const value = normalizeMatchValue(part.normalizer, values[part.fieldId])\n    if (!value) return null\n    parts.push(value)\n  }\n  return parts.join(MATCH_KEY_PART_SEPARATOR)\n}\n\n/** The key under which a lookup answer is filed. */\nexport function matchLookupKey(fieldId: string, normalized: string): string {\n  return `${fieldId}\\u0000${normalized}`\n}\n\n/** Field + normalized value → ids of the existing records holding it. */\nexport type MatchLookup = ReadonlyMap<string, readonly string[]>\n\n/** What the caller must look up: per key, the distinct normalized values the rows carry. */\nexport interface MatchLookupRequest extends MatchKeySpec {\n  values: string[]\n}\n\n/** The values each key must be looked up for, distinct, in first-seen order. */\nexport function matchLookupRequests(\n  rows: readonly Readonly<Record<string, unknown>>[],\n  keys: readonly MatchKeySpec[],\n): MatchLookupRequest[] {\n  return keys.map((key) => {\n    const values = new Set<string>()\n    for (const row of rows) {\n      const normalized = matchKeyValue(key, row)\n      if (normalized) values.add(normalized)\n    }\n    return { ...key, values: [...values] }\n  })\n}\n\n/** Builds a {@link MatchLookup} from records: each record's values under every key. */\nexport function buildMatchLookup(\n  records: Iterable<{ id: string; values: Readonly<Record<string, unknown>> }>,\n  keys: readonly MatchKeySpec[],\n): Map<string, string[]> {\n  const lookup = new Map<string, string[]>()\n  for (const record of records) {\n    for (const key of keys) {\n      const raw = key.normalizer === 'aglynId' && record.values[key.fieldId] === undefined ? record.id : record.values[key.fieldId]\n      const values = Array.isArray(raw) ? raw : [raw]\n      for (const value of values) {\n        const normalized = matchKeyValue(key, { ...record.values, [key.fieldId]: value })\n        if (!normalized) continue\n        const at = matchLookupKey(key.fieldId, normalized)\n        const ids = lookup.get(at) ?? []\n        if (!ids.includes(record.id)) ids.push(record.id)\n        lookup.set(at, ids)\n      }\n    }\n  }\n  return lookup\n}\n\n/** Which key found a row's record, and by what value. */\nexport interface MatchedVia {\n  fieldId: string\n  value: string\n}\n\n/** What a row is about. */\nexport type RowMatchOutcome =\n  | { kind: 'new' }\n  | {\n      kind: 'matched'\n      recordId: string\n      via: MatchedVia\n      /** Other records a lower-priority key pointed at — worth a warning. */\n      alsoMatched?: string[]\n    }\n  | { kind: 'ambiguous'; recordIds: string[]; via: MatchedVia }\n  | { kind: 'duplicateInFile'; firstRow: number; via: MatchedVia }\n\n/**\n * One outcome per row (see the block header). A row is a duplicate when ANY\n * key value it carries was carried by an earlier row; otherwise the keys\n * are tried in order and the first that finds a record decides.\n */\nexport function matchRows(\n  rows: readonly Readonly<Record<string, unknown>>[],\n  keys: readonly MatchKeySpec[],\n  lookup: MatchLookup,\n): RowMatchOutcome[] {\n  const firstRowOf = new Map<string, number>()\n  return rows.map((row, index) => {\n    const carried = keys\n      .map((key) => ({ key, value: matchKeyValue(key, row) }))\n      .filter((entry): entry is { key: MatchKeySpec; value: string } => Boolean(entry.value))\n\n    const duplicateOf = carried\n      .map((entry) => ({ entry, first: firstRowOf.get(matchLookupKey(entry.key.fieldId, entry.value)) }))\n      .find((found) => found.first !== undefined)\n    for (const entry of carried) {\n      const at = matchLookupKey(entry.key.fieldId, entry.value)\n      if (!firstRowOf.has(at)) firstRowOf.set(at, index)\n    }\n    if (duplicateOf) {\n      return {\n        kind: 'duplicateInFile',\n        firstRow: duplicateOf.first as number,\n        via: { fieldId: duplicateOf.entry.key.fieldId, value: duplicateOf.entry.value },\n      }\n    }\n\n    for (let at = 0; at < carried.length; at += 1) {\n      const { key, value } = carried[at] as { key: MatchKeySpec; value: string }\n      const ids = lookup.get(matchLookupKey(key.fieldId, value)) ?? []\n      if (!ids.length) continue\n      const via = { fieldId: key.fieldId, value }\n      if (ids.length > 1) return { kind: 'ambiguous', recordIds: [...ids], via }\n      const recordId = ids[0] as string\n      const others = new Set<string>()\n      for (const later of carried.slice(at + 1)) {\n        for (const id of lookup.get(matchLookupKey(later.key.fieldId, later.value)) ?? []) {\n          if (id !== recordId) others.add(id)\n        }\n      }\n      return others.size\n        ? { kind: 'matched', recordId, via, alsoMatched: [...others] }\n        : { kind: 'matched', recordId, via }\n    }\n    return { kind: 'new' }\n  })\n}\n\n/** How many rows had each outcome. */\nexport function summarizeMatches(outcomes: readonly RowMatchOutcome[]): Record<RowMatchOutcome['kind'], number> {\n  const summary = { new: 0, matched: 0, ambiguous: 0, duplicateInFile: 0 }\n  for (const outcome of outcomes) summary[outcome.kind] += 1\n  return summary\n}\n"],"names":["normalizePhone","foldText","MATCH_KEY_PART_SEPARATOR","domainOf","value","text","String","trim","toLowerCase","at","lastIndexOf","includes","slice","replace","split","test","foldName","foldSlug","normalizeMatchValue","normalizer","undefined","key","lower","instantOf","replaceAll","ms","Date","getTime","Number","parse","isFinite","toISOString","matchKeyValue","values","first","fieldId","with","length","parts","part","push","join","matchLookupKey","normalized","matchLookupRequests","rows","keys","map","Set","row","add","buildMatchLookup","records","lookup","Map","record","raw","id","Array","isArray","ids","get","set","matchRows","firstRowOf","index","carried","filter","entry","Boolean","duplicateOf","find","found","has","kind","firstRow","via","recordIds","recordId","others","later","size","alsoMatched","summarizeMatches","outcomes","summary","new","matched","ambiguous","duplicateInFile","outcome"],"mappings":"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"}

package/src/lib/data-transfer/package-plan.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ExistingPackageItem, type PackageItemComparison, type PackageItemDecision, type PackageItemStatus, type PackageManifest } from './package';
+/** The kind a reference to one of the workspace's sites carries. Answered by the engine, not a plugin. */
+export declare const TRANSFER_SITE_KIND = "site";
+/** The resource a workspace package's job is filed under: one package import runs at a time. */
+export declare const TRANSFER_PACKAGE_RESOURCE = "package";
+/** The most items one workspace package may carry. */
+export declare const TRANSFER_PACKAGE_MAX_ITEMS = 1000;
+/** The most bytes one workspace package file may carry. */
+export declare const TRANSFER_PACKAGE_MAX_BYTES = 3000000;
+/** What importing one item comes to. */
+export type TransferPackageVerdict = 'create' | 'replace' | 'keepBoth' | 'skip' | 'fail';
+export declare const TRANSFER_PACKAGE_VERDICTS: readonly TransferPackageVerdict[];
+/** What to do about a reference the package cannot satisfy. */
+export type TransferPackageDependencyChoice = 
+/** Import the package's own copy of an item the person had skipped. */
+{
+    action: 'import';
+}
+/** Point the reference at something the workspace already has. */
+ | {
+    action: 'mapTo';
+    id: string;
+}
+/** Leave the reference out of every item that names it. */
+ | {
+    action: 'dropReference';
+}
+/** Skip every item that needs it. */
+ | {
+    action: 'skipItem';
+};
+export type TransferPackageDependencyAction = TransferPackageDependencyChoice['action'];
+/** One thing a reference may be mapped to. */
+export interface TransferReferenceTarget {
+    id: string;
+    name?: string;
+}
+/** What the workspace holds of a kind no package resource owns (its sites, its mailboxes, its lists). */
+export interface TransferReferenceKind {
+    kind: string;
+    /** What one of them is called ("Mailbox"). */
+    label: string;
+    targets: TransferReferenceTarget[];
+}
+/** The warnings an import must have acknowledged before it writes. */
+export type TransferPackageWarningClass = 'replace' | 'dropReference' | 'failed';
+export declare const TRANSFER_PACKAGE_WARNING_CLASSES: readonly TransferPackageWarningClass[];
+/** Why an item is skipped or fails. */
+export type TransferPackageItemReason = 
+/** No enabled plugin owns its kind. */
+'unknownKind'
+/** The person chose to skip it. */
+ | 'chosen'
+/** It is identical to the workspace's item. */
+ | 'identical'
+/** A reference it needs was answered with "skip every item that needs it". */
+ | 'missingDependency'
+/** The owning plugin's own checks refuse it (`problems`). */
+ | 'problems';
+/** One item's line in the plan. */
+export interface TransferPackagePlanItem {
+    /** Its index in the manifest — the row the ledger and the results name. */
+    row: number;
+    /** `<kind>/<id>`, as the file names it. */
+    key: string;
+    kind: string;
+    id: string;
+    name?: string;
+    slug?: string;
+    status: PackageItemStatus;
+    comparison: PackageItemComparison;
+    matchedBy?: 'id' | 'slug' | 'name';
+    existing?: {
+        id: string;
+        name?: string;
+        slug?: string;
+    };
+    /** What will be done with it. */
+    decision: PackageItemDecision;
+    /** The decisions it may take. */
+    decisions: PackageItemDecision[];
+    /** It differs from the workspace's item and the person has not chosen yet. */
+    needsChoice: boolean;
+    verdict: TransferPackageVerdict;
+    /** The id it is written under, for a write. */
+    targetId?: string;
+    /** A kept-both copy's new name and slug. */
+    rename?: {
+        name?: string;
+        slug?: string;
+    };
+    reason?: TransferPackageItemReason;
+    /** The owning plugin's objections, each a sentence; any one fails the item. */
+    problems: string[];
+}
+/** A reference no item in the package or the workspace satisfies, and what the person chose for it. */
+export interface TransferPackageReference {
+    /** `<kind>/<id>`. */
+    key: string;
+    kind: string;
+    id: string;
+    /** What one of the kind is called. */
+    label: string;
+    /** A name for it, when the package carries it. */
+    name?: string;
+    /** The items that name it, by key. */
+    neededBy: string[];
+    /** The package carries it, and the person chose not to import it. */
+    inPackage: boolean;
+    choice: TransferPackageDependencyChoice | null;
+    /** What may be chosen for it. */
+    choices: TransferPackageDependencyAction[];
+    /** What it may be mapped to. */
+    targets: TransferReferenceTarget[];
+}
+export type TransferPackageSummary = Record<TransferPackageVerdict, number> & {
+    total: number;
+};
+/** What importing a package would do. */
+export interface TransferPackagePlan {
+    items: TransferPackagePlanItem[];
+    /** References needing (or holding) a choice. */
+    references: TransferPackageReference[];
+    /** Kinds in the file no enabled plugin owns; their items are skipped. */
+    unknownKinds: string[];
+    /** The keys of the items that write, dependencies first. */
+    order: string[];
+    /** Item key → the id it has after the import; `''` for a dropped reference. */
+    idMap: Record<string, string>;
+    summary: TransferPackageSummary;
+    /** What still blocks Apply, each a sentence. */
+    blocking: string[];
+    acknowledgementsRequired: TransferPackageWarningClass[];
+}
+export interface PlanTransferPackageInput {
+    manifest: Pick<PackageManifest, 'items'>;
+    /** The kinds a package resource owns here — every other kind is unknown. */
+    ownedKinds: ReadonlySet<string>;
+    /** What the workspace holds of every owned kind the package carries or names. */
+    existing: readonly ExistingPackageItem[];
+    /** What the workspace holds of the other kinds the items name. */
+    references?: readonly TransferReferenceKind[];
+    /** What a package kind is called, for a reference to one. */
+    kindLabels?: Readonly<Record<string, string>>;
+    /** The person's decision per item key. */
+    decisions?: Readonly<Record<string, PackageItemDecision>>;
+    /** The person's choice per reference key. */
+    dependencyChoices?: Readonly<Record<string, TransferPackageDependencyChoice>>;
+    /** The objections each item's plugin raised, by item key. */
+    problems?: Readonly<Record<string, readonly string[]>>;
+    /** A fresh id for a kept-both copy. Called once per such item, in manifest order. */
+    newId: () => string;
+}
+/**
+ * The name a kept-both copy takes: `<name> (copy)`, then `(copy 2)`,
+ * `(copy 3)`… until none of `taken` (compared caselessly).
+ */
+export declare function keepBothName(name: string, taken: Iterable<string>): string;
+/**
+ * What a resource holds now, as matching reads it: each item's content
+ * hashed with `contentHash`. A resource's `items` hook answers with this
+ * over the same content `readItems` exports, so an item exported and
+ * imported unchanged compares `identical`.
+ */
+export declare function existingPackageItemsOf<T>(kind: string, contents: ReadonlyArray<{
+    id: string;
+    name?: string;
+    slug?: string;
+    content: T;
+}>): Promise<ExistingPackageItem[]>;
+/**
+ * The plan (see the block header). Deterministic for the same input,
+ * `newId` aside: decisions the person did not make are proposed, a
+ * decision an item may not take falls back to the proposal, and a
+ * reference choice that names nothing the workspace holds is no choice.
+ */
+export declare function planTransferPackage(input: PlanTransferPackageInput): TransferPackagePlan;
+/** The warning classes a plan still needs acknowledged. */
+export declare function missingPackageAcknowledgements(plan: Pick<TransferPackagePlan, 'acknowledgementsRequired'>, acknowledged: readonly string[]): TransferPackageWarningClass[];
+/** Whether a plan may be applied: nothing blocks, every warning is acknowledged, and something writes. */
+export declare function canApplyTransferPackage(plan: Pick<TransferPackagePlan, 'acknowledgementsRequired' | 'blocking' | 'summary'>, acknowledged: readonly string[]): boolean;
+/** The id map as `remapIds` takes it. */
+export declare function packageIdMap(idMap: Readonly<Record<string, string>>): ReadonlyMap<string, string>;
+/**
+ * A reference rewritten through an id map: the id it now has, `null` when
+ * the person dropped it, or itself when nothing maps it (a reference the
+ * workspace already satisfies). The helper every `remapIds` uses.
+ */
+export declare function remapPackageReference(idMap: ReadonlyMap<string, string>, kind: string, id: string | null | undefined): string | null;