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

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

@@ -0,0 +1,190 @@
+/**
+ * @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 { TransferFieldMode, TransferPolicy } from './policy';
+import type { TransferPlanSummary, TransferRowReason, TransferWarningClass } from './plan';
+import type { TransferFormat, TransferKind } from './resource';
+/** Rows per chunk: a chunk is planned, applied and reported as one. */
+export declare const TRANSFER_CHUNK_ROWS = 200;
+/** The most writes in one batch (Firestore's limit). */
+export declare const TRANSFER_BATCH_WRITES_MAX = 500;
+/** How many records are written at once within a chunk. */
+export declare const TRANSFER_WRITE_CONCURRENCY = 8;
+/** How long an applied import may be undone. */
+export declare const TRANSFER_UNDO_WINDOW_MS: number;
+export type TransferJobStatus = 'draft' | 'analyzed' | 'planned' | 'applying' | 'applied' | 'failed' | 'undone';
+export declare const TRANSFER_JOB_STATUSES: readonly TransferJobStatus[];
+/**
+ * The moves each state allows. A state may be re-entered where the work is
+ * repeatable: re-analyzing, re-planning after a changed choice, and
+ * `applying` → `applying` as each chunk advances the cursor.
+ */
+export declare const TRANSFER_JOB_TRANSITIONS: Readonly<Record<TransferJobStatus, readonly TransferJobStatus[]>>;
+/** Whether a job may move from `from` to `to`. */
+export declare function canTransitionTransferJob(from: TransferJobStatus, to: TransferJobStatus): boolean;
+/** A move the state machine does not allow. */
+export declare class TransferJobTransitionError extends Error {
+    readonly from: TransferJobStatus;
+    readonly to: TransferJobStatus;
+    constructor(from: TransferJobStatus, to: TransferJobStatus);
+}
+/** Where applying has reached: the next chunk to write. */
+export interface TransferJobCursor {
+    chunk: number;
+    /** Rows written so far (all chunks before `chunk`). */
+    rowsDone: number;
+}
+export interface TransferJobError {
+    code: string;
+    message: string;
+    /** The chunk that failed, when one did. */
+    chunk?: number;
+}
+/** One import or export, as stored. */
+export interface TransferJob {
+    id: string;
+    /** The resource key. */
+    resource: string;
+    kind: TransferKind;
+    direction: 'import' | 'export';
+    format: TransferFormat;
+    status: TransferJobStatus;
+    orgId: string;
+    /** The site, for a host-scoped resource. */
+    hostId?: string;
+    createdBy: string;
+    createdAt: number;
+    updatedAt: number;
+    fileName?: string;
+    rowCount?: number;
+    chunkCount?: number;
+    /** Column → field id, as the person confirmed it. */
+    mapping?: Record<number, string>;
+    matchKeys?: string[];
+    policy?: TransferPolicy;
+    summary?: TransferPlanSummary;
+    acknowledged?: TransferWarningClass[];
+    cursor?: TransferJobCursor;
+    error?: TransferJobError;
+    appliedAt?: number;
+    undoneAt?: number;
+}
+/**
+ * The job moved to `to` at `now`. Entering `applied` stamps `appliedAt`;
+ * entering `undone` stamps `undoneAt`; leaving `failed` clears the error.
+ * Throws {@link TransferJobTransitionError} for a move the machine refuses.
+ */
+export declare function transitionTransferJob(job: TransferJob, to: TransferJobStatus, now: number, patch?: Partial<Omit<TransferJob, 'id' | 'status'>>): TransferJob;
+/** Whether an applied job may still be undone at `now`. */
+export declare function transferUndoAvailable(job: Pick<TransferJob, 'status' | 'appliedAt'>, now: number): boolean;
+/** When an applied job's undo closes, or `null` when it was never applied. */
+export declare function transferUndoExpiresAt(job: Pick<TransferJob, 'appliedAt'>): number | null;
+/** The ledger key that makes one row's write happen once: `<jobId>:<rowIndex>`. */
+export declare function transferLedgerKey(jobId: string, rowIndex: number): string;
+/** A ledger key read back, or `null` when it is not one. */
+export declare function parseTransferLedgerKey(key: string): {
+    jobId: string;
+    rowIndex: number;
+} | null;
+/** One chunk's span of the file. */
+export interface TransferChunkRange {
+    index: number;
+    /** First row index, inclusive. */
+    start: number;
+    /** Last row index, exclusive. */
+    end: number;
+}
+/** A file of `rowCount` rows cut into chunks of `size`. */
+export declare function transferChunkRanges(rowCount: number, size?: number): TransferChunkRange[];
+/** The chunk a row falls in. */
+export declare function transferChunkOfRow(rowIndex: number, size?: number): number;
+/** Items cut into batches of at most `max` (one batch per commit). */
+export declare function transferWriteBatches<T>(items: readonly T[], max?: number): T[][];
+/** What applying did to one row. */
+export type TransferRowOutcome = 'created' | 'updated' | 'unchanged' | 'skipped' | 'failed';
+export interface TransferRowResult {
+    row: number;
+    outcome: TransferRowOutcome;
+    recordId?: string;
+    reason?: TransferRowReason | string;
+    /** A sentence for a failure the plan did not foresee. */
+    message?: string;
+}
+/** One chunk's plan, as stored for the apply step. */
+export interface TransferChunk<Row = unknown> {
+    jobId: string;
+    index: number;
+    start: number;
+    end: number;
+    rows: Row[];
+}
+/** One chunk's results, as stored. */
+export interface TransferChunkResult {
+    jobId: string;
+    index: number;
+    results: TransferRowResult[];
+    completedAt: number;
+}
+/** Counts by outcome. */
+export type TransferResultSummary = Record<TransferRowOutcome, number> & {
+    total: number;
+};
+/** The results counted. */
+export declare function summarizeTransferResults(results: Iterable<TransferRowResult>): TransferResultSummary;
+/** What undo needs to reverse one row. */
+export interface TransferUndoEntry {
+    row: number;
+    recordId: string;
+    action: 'created' | 'updated';
+    /** For an update: each touched field's value before the import (`null` for none). */
+    previous?: Record<string, unknown>;
+    /** The values the import wrote, to tell a later edit from the import's own. */
+    written: Record<string, unknown>;
+    /** The modes the fields were written under, for the undo screen. */
+    modes?: Record<string, TransferFieldMode>;
+}
+/** One chunk's undo entries, as stored. */
+export interface TransferUndoSnapshot {
+    jobId: string;
+    chunk: number;
+    entries: TransferUndoEntry[];
+}
+/** What undo does for one row. */
+export type TransferUndoStep = {
+    action: 'delete';
+    recordId: string;
+} | {
+    action: 'restore';
+    recordId: string;
+    values: Record<string, unknown>;
+} | {
+    action: 'conflict';
+    recordId: string;
+    fields: string[];
+    values: Record<string, unknown>;
+} | {
+    action: 'nothing';
+    recordId: string;
+    why: 'gone' | 'alreadyReverted';
+};
+/**
+ * The undo step for one entry against the record as it is now (`null` when
+ * it no longer exists). A field the import wrote that still holds what the
+ * import wrote is restored; a field edited since is a conflict, and the
+ * person chooses. A created record is deleted only when untouched since;
+ * otherwise deleting it is a conflict too.
+ */
+export declare function planTransferUndo(entry: TransferUndoEntry, current: Readonly<Record<string, unknown>> | null): TransferUndoStep;

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

@@ -0,0 +1,229 @@
+/**
+ * @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.
+ */ /*==========================================
+ * TRANSFER JOBS — the shapes an import is stored and applied in.
+ *
+ * An import is a job that moves through fixed states:
+ *
+ *   draft → analyzed → planned → applying → applied → undone
+ *                         ↑          ↓
+ *                         └──── failed (resume, or re-plan)
+ *
+ *  - `draft` — the file is uploaded and nothing is read yet;
+ *  - `analyzed` — headers matched and values collected; the person maps;
+ *  - `planned` — the dry run is stored; the person reviews and acknowledges;
+ *  - `applying` — chunks are being written; the cursor says how far;
+ *  - `applied` — every chunk is written; undo is open for seven days;
+ *  - `failed` — a chunk could not be written; resuming re-enters `applying`;
+ *  - `undone` — the undo ran. Nothing follows it.
+ *
+ * Applying is chunked and idempotent: rows go in chunks of
+ * {@link TRANSFER_CHUNK_ROWS}, writes in batches of at most
+ * {@link TRANSFER_BATCH_WRITES_MAX}, and every row is recorded in a ledger
+ * under {@link transferLedgerKey} before its write is acknowledged, so a
+ * retried chunk never writes a row twice.
+ *
+ * ## Undo
+ *
+ * Before a row updates a record, the previous values of the fields it
+ * touches are snapshotted; a created record's id is kept. Undo restores
+ * the snapshot or deletes the created record — unless the record changed
+ * since the import, in which case the person is asked (keep what it holds
+ * now, or restore) rather than having a later edit silently thrown away.
+ *=========================================*/ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { transferValuesEqual } from "./policy.js";
+/** Rows per chunk: a chunk is planned, applied and reported as one. */ export const TRANSFER_CHUNK_ROWS = 200;
+/** The most writes in one batch (Firestore's limit). */ export const TRANSFER_BATCH_WRITES_MAX = 500;
+/** How many records are written at once within a chunk. */ export const TRANSFER_WRITE_CONCURRENCY = 8;
+/** How long an applied import may be undone. */ export const TRANSFER_UNDO_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+export const TRANSFER_JOB_STATUSES = [
+    'draft',
+    'analyzed',
+    'planned',
+    'applying',
+    'applied',
+    'failed',
+    'undone'
+];
+/**
+ * The moves each state allows. A state may be re-entered where the work is
+ * repeatable: re-analyzing, re-planning after a changed choice, and
+ * `applying` → `applying` as each chunk advances the cursor.
+ */ export const TRANSFER_JOB_TRANSITIONS = {
+    draft: [
+        'analyzed',
+        'failed'
+    ],
+    analyzed: [
+        'analyzed',
+        'planned',
+        'failed'
+    ],
+    planned: [
+        'analyzed',
+        'planned',
+        'applying',
+        'failed'
+    ],
+    applying: [
+        'applying',
+        'applied',
+        'failed'
+    ],
+    applied: [
+        'undone'
+    ],
+    failed: [
+        'applying',
+        'planned',
+        'analyzed'
+    ],
+    undone: []
+};
+/** Whether a job may move from `from` to `to`. */ export function canTransitionTransferJob(from, to) {
+    var _ref;
+    var _TRANSFER_JOB_TRANSITIONS_from;
+    return (_ref = (_TRANSFER_JOB_TRANSITIONS_from = TRANSFER_JOB_TRANSITIONS[from]) == null ? void 0 : _TRANSFER_JOB_TRANSITIONS_from.includes(to)) != null ? _ref : false;
+}
+/** A move the state machine does not allow. */ export class TransferJobTransitionError extends Error {
+    constructor(from, to){
+        super(`A transfer job cannot move from ${from} to ${to}.`), this.from = from, this.to = to;
+        this.name = 'TransferJobTransitionError';
+    }
+}
+/**
+ * The job moved to `to` at `now`. Entering `applied` stamps `appliedAt`;
+ * entering `undone` stamps `undoneAt`; leaving `failed` clears the error.
+ * Throws {@link TransferJobTransitionError} for a move the machine refuses.
+ */ export function transitionTransferJob(job, to, now, patch = {}) {
+    if (!canTransitionTransferJob(job.status, to)) throw new TransferJobTransitionError(job.status, to);
+    const next = _extends({}, job, patch, {
+        status: to,
+        updatedAt: now
+    });
+    if (to === 'applied') next.appliedAt = now;
+    if (to === 'undone') next.undoneAt = now;
+    if (job.status === 'failed' && to !== 'failed' && !patch.error) delete next.error;
+    return next;
+}
+/** Whether an applied job may still be undone at `now`. */ export function transferUndoAvailable(job, now) {
+    return job.status === 'applied' && job.appliedAt !== undefined && now - job.appliedAt <= TRANSFER_UNDO_WINDOW_MS;
+}
+/** When an applied job's undo closes, or `null` when it was never applied. */ export function transferUndoExpiresAt(job) {
+    return job.appliedAt === undefined ? null : job.appliedAt + TRANSFER_UNDO_WINDOW_MS;
+}
+/** The ledger key that makes one row's write happen once: `<jobId>:<rowIndex>`. */ export function transferLedgerKey(jobId, rowIndex) {
+    if (!jobId || jobId.includes(':') || jobId.includes('/')) throw new Error(`"${jobId}" is not a job id.`);
+    if (!Number.isInteger(rowIndex) || rowIndex < 0) throw new Error(`${rowIndex} is not a row index.`);
+    return `${jobId}:${rowIndex}`;
+}
+/** A ledger key read back, or `null` when it is not one. */ export function parseTransferLedgerKey(key) {
+    const match = /^([^:/]+):(\d+)$/.exec(String(key != null ? key : ''));
+    if (!match) return null;
+    return {
+        jobId: match[1],
+        rowIndex: Number(match[2])
+    };
+}
+/** A file of `rowCount` rows cut into chunks of `size`. */ export function transferChunkRanges(rowCount, size = TRANSFER_CHUNK_ROWS) {
+    const ranges = [];
+    if (!(size > 0)) return ranges;
+    for(let start = 0, index = 0; start < rowCount; start += size, index += 1){
+        ranges.push({
+            index,
+            start,
+            end: Math.min(rowCount, start + size)
+        });
+    }
+    return ranges;
+}
+/** The chunk a row falls in. */ export function transferChunkOfRow(rowIndex, size = TRANSFER_CHUNK_ROWS) {
+    return Math.floor(rowIndex / size);
+}
+/** Items cut into batches of at most `max` (one batch per commit). */ export function transferWriteBatches(items, max = TRANSFER_BATCH_WRITES_MAX) {
+    const batches = [];
+    for(let at = 0; at < items.length; at += max)batches.push(items.slice(at, at + max));
+    return batches;
+}
+/** The results counted. */ export function summarizeTransferResults(results) {
+    const summary = {
+        created: 0,
+        updated: 0,
+        unchanged: 0,
+        skipped: 0,
+        failed: 0,
+        total: 0
+    };
+    for (const result of results){
+        summary[result.outcome] += 1;
+        summary.total += 1;
+    }
+    return summary;
+}
+/**
+ * The undo step for one entry against the record as it is now (`null` when
+ * it no longer exists). A field the import wrote that still holds what the
+ * import wrote is restored; a field edited since is a conflict, and the
+ * person chooses. A created record is deleted only when untouched since;
+ * otherwise deleting it is a conflict too.
+ */ export function planTransferUndo(entry, current) {
+    var _entry_previous;
+    if (!current) return {
+        action: 'nothing',
+        recordId: entry.recordId,
+        why: 'gone'
+    };
+    const edited = Object.keys(entry.written).filter((fieldId)=>!transferValuesEqual(current[fieldId], entry.written[fieldId]));
+    if (entry.action === 'created') {
+        return edited.length ? {
+            action: 'conflict',
+            recordId: entry.recordId,
+            fields: edited,
+            values: {}
+        } : {
+            action: 'delete',
+            recordId: entry.recordId
+        };
+    }
+    const previous = (_entry_previous = entry.previous) != null ? _entry_previous : {};
+    const values = {};
+    const conflicts = [];
+    for (const fieldId of Object.keys(entry.written)){
+        var _previous_fieldId;
+        const was = (_previous_fieldId = previous[fieldId]) != null ? _previous_fieldId : null;
+        if (transferValuesEqual(current[fieldId], was)) continue;
+        if (edited.includes(fieldId)) conflicts.push(fieldId);
+        values[fieldId] = was;
+    }
+    if (conflicts.length) return {
+        action: 'conflict',
+        recordId: entry.recordId,
+        fields: conflicts,
+        values
+    };
+    if (!Object.keys(values).length) return {
+        action: 'nothing',
+        recordId: entry.recordId,
+        why: 'alreadyReverted'
+    };
+    return {
+        action: 'restore',
+        recordId: entry.recordId,
+        values
+    };
+}
+
+//# sourceMappingURL=job.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/data-transfer/job.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 * TRANSFER JOBS — the shapes an import is stored and applied in.\n *\n * An import is a job that moves through fixed states:\n *\n *   draft → analyzed → planned → applying → applied → undone\n *                         ↑          ↓\n *                         └──── failed (resume, or re-plan)\n *\n *  - `draft` — the file is uploaded and nothing is read yet;\n *  - `analyzed` — headers matched and values collected; the person maps;\n *  - `planned` — the dry run is stored; the person reviews and acknowledges;\n *  - `applying` — chunks are being written; the cursor says how far;\n *  - `applied` — every chunk is written; undo is open for seven days;\n *  - `failed` — a chunk could not be written; resuming re-enters `applying`;\n *  - `undone` — the undo ran. Nothing follows it.\n *\n * Applying is chunked and idempotent: rows go in chunks of\n * {@link TRANSFER_CHUNK_ROWS}, writes in batches of at most\n * {@link TRANSFER_BATCH_WRITES_MAX}, and every row is recorded in a ledger\n * under {@link transferLedgerKey} before its write is acknowledged, so a\n * retried chunk never writes a row twice.\n *\n * ## Undo\n *\n * Before a row updates a record, the previous values of the fields it\n * touches are snapshotted; a created record's id is kept. Undo restores\n * the snapshot or deletes the created record — unless the record changed\n * since the import, in which case the person is asked (keep what it holds\n * now, or restore) rather than having a later edit silently thrown away.\n *=========================================*/\n\nimport type { TransferFieldMode, TransferPolicy } from './policy'\nimport type { TransferPlanSummary, TransferRowReason, TransferWarningClass } from './plan'\nimport { transferValuesEqual } from './policy'\nimport type { TransferFormat, TransferKind } from './resource'\n\n/** Rows per chunk: a chunk is planned, applied and reported as one. */\nexport const TRANSFER_CHUNK_ROWS = 200\n\n/** The most writes in one batch (Firestore's limit). */\nexport const TRANSFER_BATCH_WRITES_MAX = 500\n\n/** How many records are written at once within a chunk. */\nexport const TRANSFER_WRITE_CONCURRENCY = 8\n\n/** How long an applied import may be undone. */\nexport const TRANSFER_UNDO_WINDOW_MS = 7 * 24 * 60 * 60 * 1000\n\nexport type TransferJobStatus = 'draft' | 'analyzed' | 'planned' | 'applying' | 'applied' | 'failed' | 'undone'\n\nexport const TRANSFER_JOB_STATUSES: readonly TransferJobStatus[] = [\n  'draft',\n  'analyzed',\n  'planned',\n  'applying',\n  'applied',\n  'failed',\n  'undone',\n]\n\n/**\n * The moves each state allows. A state may be re-entered where the work is\n * repeatable: re-analyzing, re-planning after a changed choice, and\n * `applying` → `applying` as each chunk advances the cursor.\n */\nexport const TRANSFER_JOB_TRANSITIONS: Readonly<Record<TransferJobStatus, readonly TransferJobStatus[]>> = {\n  draft: ['analyzed', 'failed'],\n  analyzed: ['analyzed', 'planned', 'failed'],\n  planned: ['analyzed', 'planned', 'applying', 'failed'],\n  applying: ['applying', 'applied', 'failed'],\n  applied: ['undone'],\n  failed: ['applying', 'planned', 'analyzed'],\n  undone: [],\n}\n\n/** Whether a job may move from `from` to `to`. */\nexport function canTransitionTransferJob(from: TransferJobStatus, to: TransferJobStatus): boolean {\n  return TRANSFER_JOB_TRANSITIONS[from]?.includes(to) ?? false\n}\n\n/** A move the state machine does not allow. */\nexport class TransferJobTransitionError extends Error {\n  constructor(\n    readonly from: TransferJobStatus,\n    readonly to: TransferJobStatus,\n  ) {\n    super(`A transfer job cannot move from ${from} to ${to}.`)\n    this.name = 'TransferJobTransitionError'\n  }\n}\n\n/** Where applying has reached: the next chunk to write. */\nexport interface TransferJobCursor {\n  chunk: number\n  /** Rows written so far (all chunks before `chunk`). */\n  rowsDone: number\n}\n\nexport interface TransferJobError {\n  code: string\n  message: string\n  /** The chunk that failed, when one did. */\n  chunk?: number\n}\n\n/** One import or export, as stored. */\nexport interface TransferJob {\n  id: string\n  /** The resource key. */\n  resource: string\n  kind: TransferKind\n  direction: 'import' | 'export'\n  format: TransferFormat\n  status: TransferJobStatus\n  orgId: string\n  /** The site, for a host-scoped resource. */\n  hostId?: string\n  createdBy: string\n  createdAt: number\n  updatedAt: number\n  fileName?: string\n  rowCount?: number\n  chunkCount?: number\n  /** Column → field id, as the person confirmed it. */\n  mapping?: Record<number, string>\n  matchKeys?: string[]\n  policy?: TransferPolicy\n  summary?: TransferPlanSummary\n  acknowledged?: TransferWarningClass[]\n  cursor?: TransferJobCursor\n  error?: TransferJobError\n  appliedAt?: number\n  undoneAt?: number\n}\n\n/**\n * The job moved to `to` at `now`. Entering `applied` stamps `appliedAt`;\n * entering `undone` stamps `undoneAt`; leaving `failed` clears the error.\n * Throws {@link TransferJobTransitionError} for a move the machine refuses.\n */\nexport function transitionTransferJob(\n  job: TransferJob,\n  to: TransferJobStatus,\n  now: number,\n  patch: Partial<Omit<TransferJob, 'id' | 'status'>> = {},\n): TransferJob {\n  if (!canTransitionTransferJob(job.status, to)) throw new TransferJobTransitionError(job.status, to)\n  const next: TransferJob = { ...job, ...patch, status: to, updatedAt: now }\n  if (to === 'applied') next.appliedAt = now\n  if (to === 'undone') next.undoneAt = now\n  if (job.status === 'failed' && to !== 'failed' && !patch.error) delete next.error\n  return next\n}\n\n/** Whether an applied job may still be undone at `now`. */\nexport function transferUndoAvailable(job: Pick<TransferJob, 'status' | 'appliedAt'>, now: number): boolean {\n  return job.status === 'applied' && job.appliedAt !== undefined && now - job.appliedAt <= TRANSFER_UNDO_WINDOW_MS\n}\n\n/** When an applied job's undo closes, or `null` when it was never applied. */\nexport function transferUndoExpiresAt(job: Pick<TransferJob, 'appliedAt'>): number | null {\n  return job.appliedAt === undefined ? null : job.appliedAt + TRANSFER_UNDO_WINDOW_MS\n}\n\n/** The ledger key that makes one row's write happen once: `<jobId>:<rowIndex>`. */\nexport function transferLedgerKey(jobId: string, rowIndex: number): string {\n  if (!jobId || jobId.includes(':') || jobId.includes('/')) throw new Error(`\"${jobId}\" is not a job id.`)\n  if (!Number.isInteger(rowIndex) || rowIndex < 0) throw new Error(`${rowIndex} is not a row index.`)\n  return `${jobId}:${rowIndex}`\n}\n\n/** A ledger key read back, or `null` when it is not one. */\nexport function parseTransferLedgerKey(key: string): { jobId: string; rowIndex: number } | null {\n  const match = /^([^:/]+):(\\d+)$/.exec(String(key ?? ''))\n  if (!match) return null\n  return { jobId: match[1] as string, rowIndex: Number(match[2]) }\n}\n\n/** One chunk's span of the file. */\nexport interface TransferChunkRange {\n  index: number\n  /** First row index, inclusive. */\n  start: number\n  /** Last row index, exclusive. */\n  end: number\n}\n\n/** A file of `rowCount` rows cut into chunks of `size`. */\nexport function transferChunkRanges(rowCount: number, size = TRANSFER_CHUNK_ROWS): TransferChunkRange[] {\n  const ranges: TransferChunkRange[] = []\n  if (!(size > 0)) return ranges\n  for (let start = 0, index = 0; start < rowCount; start += size, index += 1) {\n    ranges.push({ index, start, end: Math.min(rowCount, start + size) })\n  }\n  return ranges\n}\n\n/** The chunk a row falls in. */\nexport function transferChunkOfRow(rowIndex: number, size = TRANSFER_CHUNK_ROWS): number {\n  return Math.floor(rowIndex / size)\n}\n\n/** Items cut into batches of at most `max` (one batch per commit). */\nexport function transferWriteBatches<T>(items: readonly T[], max = TRANSFER_BATCH_WRITES_MAX): T[][] {\n  const batches: T[][] = []\n  for (let at = 0; at < items.length; at += max) batches.push(items.slice(at, at + max))\n  return batches\n}\n\n/** What applying did to one row. */\nexport type TransferRowOutcome = 'created' | 'updated' | 'unchanged' | 'skipped' | 'failed'\n\nexport interface TransferRowResult {\n  row: number\n  outcome: TransferRowOutcome\n  recordId?: string\n  reason?: TransferRowReason | string\n  /** A sentence for a failure the plan did not foresee. */\n  message?: string\n}\n\n/** One chunk's plan, as stored for the apply step. */\nexport interface TransferChunk<Row = unknown> {\n  jobId: string\n  index: number\n  start: number\n  end: number\n  rows: Row[]\n}\n\n/** One chunk's results, as stored. */\nexport interface TransferChunkResult {\n  jobId: string\n  index: number\n  results: TransferRowResult[]\n  completedAt: number\n}\n\n/** Counts by outcome. */\nexport type TransferResultSummary = Record<TransferRowOutcome, number> & { total: number }\n\n/** The results counted. */\nexport function summarizeTransferResults(results: Iterable<TransferRowResult>): TransferResultSummary {\n  const summary: TransferResultSummary = { created: 0, updated: 0, unchanged: 0, skipped: 0, failed: 0, total: 0 }\n  for (const result of results) {\n    summary[result.outcome] += 1\n    summary.total += 1\n  }\n  return summary\n}\n\n/** What undo needs to reverse one row. */\nexport interface TransferUndoEntry {\n  row: number\n  recordId: string\n  action: 'created' | 'updated'\n  /** For an update: each touched field's value before the import (`null` for none). */\n  previous?: Record<string, unknown>\n  /** The values the import wrote, to tell a later edit from the import's own. */\n  written: Record<string, unknown>\n  /** The modes the fields were written under, for the undo screen. */\n  modes?: Record<string, TransferFieldMode>\n}\n\n/** One chunk's undo entries, as stored. */\nexport interface TransferUndoSnapshot {\n  jobId: string\n  chunk: number\n  entries: TransferUndoEntry[]\n}\n\n/** What undo does for one row. */\nexport type TransferUndoStep =\n  | { action: 'delete'; recordId: string }\n  | { action: 'restore'; recordId: string; values: Record<string, unknown> }\n  | { action: 'conflict'; recordId: string; fields: string[]; values: Record<string, unknown> }\n  | { action: 'nothing'; recordId: string; why: 'gone' | 'alreadyReverted' }\n\n/**\n * The undo step for one entry against the record as it is now (`null` when\n * it no longer exists). A field the import wrote that still holds what the\n * import wrote is restored; a field edited since is a conflict, and the\n * person chooses. A created record is deleted only when untouched since;\n * otherwise deleting it is a conflict too.\n */\nexport function planTransferUndo(\n  entry: TransferUndoEntry,\n  current: Readonly<Record<string, unknown>> | null,\n): TransferUndoStep {\n  if (!current) return { action: 'nothing', recordId: entry.recordId, why: 'gone' }\n  const edited = Object.keys(entry.written).filter(\n    (fieldId) => !transferValuesEqual(current[fieldId], entry.written[fieldId]),\n  )\n  if (entry.action === 'created') {\n    return edited.length\n      ? { action: 'conflict', recordId: entry.recordId, fields: edited, values: {} }\n      : { action: 'delete', recordId: entry.recordId }\n  }\n  const previous = entry.previous ?? {}\n  const values: Record<string, unknown> = {}\n  const conflicts: string[] = []\n  for (const fieldId of Object.keys(entry.written)) {\n    const was = previous[fieldId] ?? null\n    if (transferValuesEqual(current[fieldId], was)) continue\n    if (edited.includes(fieldId)) conflicts.push(fieldId)\n    values[fieldId] = was\n  }\n  if (conflicts.length) return { action: 'conflict', recordId: entry.recordId, fields: conflicts, values }\n  if (!Object.keys(values).length) return { action: 'nothing', recordId: entry.recordId, why: 'alreadyReverted' }\n  return { action: 'restore', recordId: entry.recordId, values }\n}\n"],"names":["transferValuesEqual","TRANSFER_CHUNK_ROWS","TRANSFER_BATCH_WRITES_MAX","TRANSFER_WRITE_CONCURRENCY","TRANSFER_UNDO_WINDOW_MS","TRANSFER_JOB_STATUSES","TRANSFER_JOB_TRANSITIONS","draft","analyzed","planned","applying","applied","failed","undone","canTransitionTransferJob","from","to","includes","TransferJobTransitionError","Error","name","transitionTransferJob","job","now","patch","status","next","updatedAt","appliedAt","undoneAt","error","transferUndoAvailable","undefined","transferUndoExpiresAt","transferLedgerKey","jobId","rowIndex","Number","isInteger","parseTransferLedgerKey","key","match","exec","String","transferChunkRanges","rowCount","size","ranges","start","index","push","end","Math","min","transferChunkOfRow","floor","transferWriteBatches","items","max","batches","at","length","slice","summarizeTransferResults","results","summary","created","updated","unchanged","skipped","total","result","outcome","planTransferUndo","entry","current","action","recordId","why","edited","Object","keys","written","filter","fieldId","fields","values","previous","conflicts","was"],"mappings":"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"}

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

@@ -0,0 +1,45 @@
+/**
+ * @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.
+ */
+/** A record a lookup value may mean, offered when the value names none exactly. */
+export interface TransferLookupSuggestion {
+    recordId: string;
+    label: string;
+}
+/** Marks a value the person chose to create; no Aglyn id contains a colon. */
+export declare const TRANSFER_LOOKUP_NEW_PREFIX = "new:";
+/** The value a row carries for a record the plugin creates from `name`. */
+export declare function transferLookupNewValue(name: string): string;
+/** The name behind a {@link transferLookupNewValue}, or `null` for any other value. */
+export declare function transferLookupNewName(value: unknown): string | null;
+/**
+ * The key a lookup value's choice is filed under: the text trimmed and
+ * lowercased, so "Acme" and "acme " are one decision.
+ */
+export declare function transferLookupKey(value: unknown): string;
+/**
+ * Whether a cell could be an Aglyn id, worth asking the target for by id
+ * before reading it as a name: one word of letters, digits, `-` and `_`.
+ */
+export declare function mayBeTransferRecordId(value: unknown): boolean;
+/**
+ * The closest candidates to `value`, best first: at most `limit`, each at
+ * least `threshold` similar (`textSimilarity`), one per record.
+ */
+export declare function rankTransferLookupSuggestions(value: string, candidates: readonly TransferLookupSuggestion[], options?: {
+    limit?: number;
+    threshold?: number;
+}): TransferLookupSuggestion[];

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

@@ -0,0 +1,71 @@
+/**
+ * @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.
+ */ /*==========================================
+ * LOOKUP COLUMNS — a cell that names another record (AGL-3541).
+ *
+ * A `lookup` field holds a record of another resource: a contact's company,
+ * a deal's contact, a task's owner. A file names that record the way a
+ * person would — "Acme", `acme.com`, `ana@acme.com` — or by its Aglyn ID,
+ * and the job engine resolves each distinct value through the target's own
+ * `lookup` hook. A value that names no record, or several, is the person's
+ * to decide: create the record, use a similar one, leave the field blank,
+ * or refuse the rows (`TransferLookupChoice`).
+ *
+ * What a row carries once resolved is the record's id. A value the person
+ * chose to CREATE is carried as {@link transferLookupNewValue} — the text
+ * behind a marker no Aglyn id can hold — so the plugin that writes the row
+ * creates the record (once, however many rows name it) on its own path.
+ *=========================================*/ import { textSimilarity } from "./similarity.js";
+/** Marks a value the person chose to create; no Aglyn id contains a colon. */ export const TRANSFER_LOOKUP_NEW_PREFIX = 'new:';
+/** The value a row carries for a record the plugin creates from `name`. */ export function transferLookupNewValue(name) {
+    return `${TRANSFER_LOOKUP_NEW_PREFIX}${name.trim()}`;
+}
+/** The name behind a {@link transferLookupNewValue}, or `null` for any other value. */ export function transferLookupNewName(value) {
+    if (typeof value !== 'string' || !value.startsWith(TRANSFER_LOOKUP_NEW_PREFIX)) return null;
+    const name = value.slice(TRANSFER_LOOKUP_NEW_PREFIX.length).trim();
+    return name || null;
+}
+/**
+ * The key a lookup value's choice is filed under: the text trimmed and
+ * lowercased, so "Acme" and "acme " are one decision.
+ */ export function transferLookupKey(value) {
+    return String(value != null ? value : '').trim().toLowerCase();
+}
+/**
+ * Whether a cell could be an Aglyn id, worth asking the target for by id
+ * before reading it as a name: one word of letters, digits, `-` and `_`.
+ */ export function mayBeTransferRecordId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{6,128}$/.test(value.trim());
+}
+/**
+ * The closest candidates to `value`, best first: at most `limit`, each at
+ * least `threshold` similar (`textSimilarity`), one per record.
+ */ export function rankTransferLookupSuggestions(value, candidates, options = {}) {
+    var _options_limit, _options_threshold;
+    const limit = (_options_limit = options.limit) != null ? _options_limit : 3;
+    const threshold = (_options_threshold = options.threshold) != null ? _options_threshold : 0.5;
+    const seen = new Set();
+    return candidates.map((candidate)=>({
+            candidate,
+            score: textSimilarity(value, candidate.label)
+        })).filter((entry)=>entry.score >= threshold).sort((a, b)=>b.score - a.score).filter((entry)=>{
+        if (seen.has(entry.candidate.recordId)) return false;
+        seen.add(entry.candidate.recordId);
+        return true;
+    }).slice(0, limit).map((entry)=>entry.candidate);
+}
+
+//# sourceMappingURL=lookup.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/data-transfer/lookup.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 * LOOKUP COLUMNS — a cell that names another record (AGL-3541).\n *\n * A `lookup` field holds a record of another resource: a contact's company,\n * a deal's contact, a task's owner. A file names that record the way a\n * person would — \"Acme\", `acme.com`, `ana@acme.com` — or by its Aglyn ID,\n * and the job engine resolves each distinct value through the target's own\n * `lookup` hook. A value that names no record, or several, is the person's\n * to decide: create the record, use a similar one, leave the field blank,\n * or refuse the rows (`TransferLookupChoice`).\n *\n * What a row carries once resolved is the record's id. A value the person\n * chose to CREATE is carried as {@link transferLookupNewValue} — the text\n * behind a marker no Aglyn id can hold — so the plugin that writes the row\n * creates the record (once, however many rows name it) on its own path.\n *=========================================*/\n\nimport { textSimilarity } from './similarity'\n\n/** A record a lookup value may mean, offered when the value names none exactly. */\nexport interface TransferLookupSuggestion {\n  recordId: string\n  label: string\n}\n\n/** Marks a value the person chose to create; no Aglyn id contains a colon. */\nexport const TRANSFER_LOOKUP_NEW_PREFIX = 'new:'\n\n/** The value a row carries for a record the plugin creates from `name`. */\nexport function transferLookupNewValue(name: string): string {\n  return `${TRANSFER_LOOKUP_NEW_PREFIX}${name.trim()}`\n}\n\n/** The name behind a {@link transferLookupNewValue}, or `null` for any other value. */\nexport function transferLookupNewName(value: unknown): string | null {\n  if (typeof value !== 'string' || !value.startsWith(TRANSFER_LOOKUP_NEW_PREFIX)) return null\n  const name = value.slice(TRANSFER_LOOKUP_NEW_PREFIX.length).trim()\n  return name || null\n}\n\n/**\n * The key a lookup value's choice is filed under: the text trimmed and\n * lowercased, so \"Acme\" and \"acme \" are one decision.\n */\nexport function transferLookupKey(value: unknown): string {\n  return String(value ?? '').trim().toLowerCase()\n}\n\n/**\n * Whether a cell could be an Aglyn id, worth asking the target for by id\n * before reading it as a name: one word of letters, digits, `-` and `_`.\n */\nexport function mayBeTransferRecordId(value: unknown): boolean {\n  return typeof value === 'string' && /^[A-Za-z0-9_-]{6,128}$/.test(value.trim())\n}\n\n/**\n * The closest candidates to `value`, best first: at most `limit`, each at\n * least `threshold` similar (`textSimilarity`), one per record.\n */\nexport function rankTransferLookupSuggestions(\n  value: string,\n  candidates: readonly TransferLookupSuggestion[],\n  options: { limit?: number; threshold?: number } = {},\n): TransferLookupSuggestion[] {\n  const limit = options.limit ?? 3\n  const threshold = options.threshold ?? 0.5\n  const seen = new Set<string>()\n  return candidates\n    .map((candidate) => ({ candidate, score: textSimilarity(value, candidate.label) }))\n    .filter((entry) => entry.score >= threshold)\n    .sort((a, b) => b.score - a.score)\n    .filter((entry) => {\n      if (seen.has(entry.candidate.recordId)) return false\n      seen.add(entry.candidate.recordId)\n      return true\n    })\n    .slice(0, limit)\n    .map((entry) => entry.candidate)\n}\n"],"names":["textSimilarity","TRANSFER_LOOKUP_NEW_PREFIX","transferLookupNewValue","name","trim","transferLookupNewName","value","startsWith","slice","length","transferLookupKey","String","toLowerCase","mayBeTransferRecordId","test","rankTransferLookupSuggestions","candidates","options","limit","threshold","seen","Set","map","candidate","score","label","filter","entry","sort","a","b","has","recordId","add"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;2CAe2C,GAE3C,SAASA,cAAc,QAAQ,kBAAc;AAQ7C,4EAA4E,GAC5E,OAAO,MAAMC,6BAA6B,OAAM;AAEhD,yEAAyE,GACzE,OAAO,SAASC,uBAAuBC,IAAY;IACjD,OAAO,GAAGF,6BAA6BE,KAAKC,IAAI,IAAI;AACtD;AAEA,qFAAqF,GACrF,OAAO,SAASC,sBAAsBC,KAAc;IAClD,IAAI,OAAOA,UAAU,YAAY,CAACA,MAAMC,UAAU,CAACN,6BAA6B,OAAO;IACvF,MAAME,OAAOG,MAAME,KAAK,CAACP,2BAA2BQ,MAAM,EAAEL,IAAI;IAChE,OAAOD,QAAQ;AACjB;AAEA;;;CAGC,GACD,OAAO,SAASO,kBAAkBJ,KAAc;IAC9C,OAAOK,OAAOL,gBAAAA,QAAS,IAAIF,IAAI,GAAGQ,WAAW;AAC/C;AAEA;;;CAGC,GACD,OAAO,SAASC,sBAAsBP,KAAc;IAClD,OAAO,OAAOA,UAAU,YAAY,yBAAyBQ,IAAI,CAACR,MAAMF,IAAI;AAC9E;AAEA;;;CAGC,GACD,OAAO,SAASW,8BACdT,KAAa,EACbU,UAA+C,EAC/CC,UAAkD,CAAC,CAAC;QAEtCA,gBACIA;IADlB,MAAMC,SAAQD,iBAAAA,QAAQC,KAAK,YAAbD,iBAAiB;IAC/B,MAAME,aAAYF,qBAAAA,QAAQE,SAAS,YAAjBF,qBAAqB;IACvC,MAAMG,OAAO,IAAIC;IACjB,OAAOL,WACJM,GAAG,CAAC,CAACC,YAAe,CAAA;YAAEA;YAAWC,OAAOxB,eAAeM,OAAOiB,UAAUE,KAAK;QAAE,CAAA,GAC/EC,MAAM,CAAC,CAACC,QAAUA,MAAMH,KAAK,IAAIL,WACjCS,IAAI,CAAC,CAACC,GAAGC,IAAMA,EAAEN,KAAK,GAAGK,EAAEL,KAAK,EAChCE,MAAM,CAAC,CAACC;QACP,IAAIP,KAAKW,GAAG,CAACJ,MAAMJ,SAAS,CAACS,QAAQ,GAAG,OAAO;QAC/CZ,KAAKa,GAAG,CAACN,MAAMJ,SAAS,CAACS,QAAQ;QACjC,OAAO;IACT,GACCxB,KAAK,CAAC,GAAGU,OACTI,GAAG,CAAC,CAACK,QAAUA,MAAMJ,SAAS;AACnC"}