@memberjunction/record-comparison 0.0.1 → 5.44.0

package/README.md

@@ -1,45 +1,53 @@
 # @memberjunction/record-comparison
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/record-comparison`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Framework-agnostic **record comparison** primitive for MemberJunction.
+
+`RecordComparisonEngine` loads a set of records for a single entity and computes a
+structured, field-level delta between them — a survivor candidate plus its potential
+matches diffed column-by-column. It performs a read-only load (`RunView` with
+`ResultType: 'simple'` and a targeted field list) and never mutates records.
+
+## Why this package exists
+
+The comparison logic is needed by two callers that sit on **opposite sides** of the
+dependency graph:
+
+- The **LLM duplicate-detection reasoning path** (`@memberjunction/ai-vector-dupe`),
+  which feeds the differing-field deltas to the reasoning provider as context.
+- The **server/UI side-by-side comparison panel**
+  (`@memberjunction/core-entities-server` → `MJServer` resolver → GraphQL client →
+  Angular `record-merge`).
+
+`@memberjunction/core-entities-server` depends on `@memberjunction/ai-vector-dupe`, so
+the dupe package sits *lower* in the graph and cannot reach an engine that lives in the
+server package without creating a build cycle. Hoisting the engine into this low-level
+package (its only dependency is `@memberjunction/core`) gives both sides a single
+implementation with no cycle and no duplicated delta logic.
+
+## Usage
+
+```typescript
+import { RecordComparisonEngine } from '@memberjunction/record-comparison';
+import { CompositeKey } from '@memberjunction/core';
+
+const engine = new RecordComparisonEngine();
+
+// By entity name (resolver / UI path) — resolves the entity from metadata.
+const result = await engine.CompareRecords(
+  { EntityName: 'Accounts', Keys: [survivorKey, candidateKey] },
+  contextUser,
+  provider // request-scoped IMetadataProvider (multi-provider safety)
+);
+
+// With an already-resolved EntityInfo + an injected RunView (dupe path) — skips the
+// by-name lookup and reuses the caller's request-scoped RunView.
+const result2 = await engine.CompareRecordsForEntity(
+  entityInfo,
+  [sourceKey, ...candidateKeys],
+  contextUser,
+  { runView }
+);
+```
+
+`result.Fields` is a plain-data delta matrix (no `BaseEntity` instances), so it
+serializes cleanly across GraphQL and into a reasoning prompt.

package/dist/RecordComparisonEngine.d.ts

@@ -0,0 +1,193 @@
+import { RunView, CompositeKey, EntityInfo, EntityFieldInfo, UserInfo, IMetadataProvider } from '@memberjunction/core';
+/**
+ * Input to {@link RecordComparisonEngine.CompareRecords}.
+ *
+ * Describes the set of records (a survivor candidate plus its potential matches)
+ * to load and diff field-by-field for a single entity.
+ */
+export interface RecordComparisonInput {
+    /** Registered entity name (e.g. "Accounts"), NOT the physical table name. */
+    EntityName: string;
+    /**
+     * The composite keys of the records to compare. By convention the first key is
+     * the survivor candidate and the remainder are potential matches, but the engine
+     * treats all records uniformly — ordering is preserved in the output column index.
+     */
+    Keys: CompositeKey[];
+    /**
+     * Optional include-list of field names to restrict the comparison to. When omitted,
+     * all visible (non-PK, non-system) fields are compared. Field names are matched
+     * case-insensitively against the entity's field metadata.
+     */
+    IncludeFields?: string[];
+}
+/**
+ * One record loaded for comparison. The `Key` correlates this record back to the
+ * input column index; `Values` is a plain map of fieldName → value for that record.
+ */
+export interface RecordComparisonRecord {
+    /** Zero-based index aligned with the input `Keys` array (the comparison column). */
+    ColumnIndex: number;
+    /** The composite key identifying this record (as supplied in the input). */
+    Key: CompositeKey;
+    /** A human-readable label for the record (name-field value when available, else the key). */
+    Label: string;
+    /** Plain field-name → value map for this record (only the compared fields). */
+    Values: Record<string, RecordFieldValue>;
+}
+/** A scalar field value as loaded from the database (never a BaseEntity). */
+export type RecordFieldValue = string | number | boolean | null;
+/**
+ * Options for {@link RecordComparisonEngine.CompareRecordsForEntity}.
+ */
+export interface RecordComparisonOptions {
+    /**
+     * Optional include-list of field names. When omitted, all visible (non-PK, non-system)
+     * fields are compared. Matched case-insensitively against the entity's field metadata.
+     */
+    IncludeFields?: string[];
+    /**
+     * An already-constructed `RunView` to load the records through. When supplied, it is used
+     * verbatim, so callers can thread their own request-scoped/provider-bound RunView (e.g. the
+     * duplicate detector). When omitted, a RunView is built from {@link RecordComparisonOptions.Provider}.
+     */
+    RunViewInstance?: RunView;
+    /** Request-scoped metadata provider (multi-provider safety) used to build a RunView when one isn't supplied. */
+    Provider?: IMetadataProvider;
+}
+/**
+ * The per-record value of a single field within a {@link RecordComparisonFieldDelta}.
+ */
+export interface RecordComparisonFieldCell {
+    /** Column index aligned with {@link RecordComparisonRecord.ColumnIndex}. */
+    ColumnIndex: number;
+    /** The field's value for this record. */
+    Value: RecordFieldValue;
+    /**
+     * True when this cell's value is equal (case-insensitive, trimmed) to the
+     * reference cell (column 0, the survivor candidate). Column 0 is always true.
+     */
+    EqualsReference: boolean;
+}
+/**
+ * The delta for a single field across all compared records.
+ */
+export interface RecordComparisonFieldDelta {
+    /** Field name (matches the entity field metadata Name). */
+    FieldName: string;
+    /** Display name for the field (falls back to FieldName). */
+    DisplayName: string;
+    /** Optional grouping category from the field metadata. */
+    Category: string | null;
+    /** Per-record values for this field, in column order. */
+    Cells: RecordComparisonFieldCell[];
+    /**
+     * True when at least one record's value differs from the reference (column 0).
+     * False when every record shares the same value.
+     */
+    Differs: boolean;
+}
+/**
+ * The serializable result of comparing a set of records: the loaded records plus a
+ * per-field delta matrix. This is the LLM "deltas" payload and (eventually) the UI
+ * side-by-side model — it is plain-data only and contains no BaseEntity instances.
+ */
+export interface RecordComparisonResult {
+    /** Whether the comparison succeeded. */
+    Success: boolean;
+    /** Populated when {@link Success} is false. */
+    ErrorMessage?: string;
+    /** Registered entity name that was compared. */
+    EntityName: string;
+    /** The loaded records, in input column order. */
+    Records: RecordComparisonRecord[];
+    /** The per-field delta matrix. Only fields with at least one non-empty value are included. */
+    Fields: RecordComparisonFieldDelta[];
+}
+/**
+ * Framework-agnostic engine that loads a set of records for one entity and computes a
+ * structured field-level delta between them.
+ *
+ * This is the shared comparison primitive used by the LLM reasoning path (it feeds the
+ * "deltas" context to the reasoning provider) and, opportunistically, by the UI
+ * side-by-side comparison panel. It performs a read-only load (`RunView` with
+ * `ResultType: 'simple'` + targeted `Fields`) — it never mutates records.
+ *
+ * No Angular, no Router, no resolver coupling. Server-side: always thread `contextUser`
+ * and (in multi-provider scenarios) the request-scoped `provider`.
+ */
+export declare class RecordComparisonEngine {
+    /**
+     * Loads the requested records and computes the field-delta matrix.
+     *
+     * @param input the entity, keys, and optional field include-list to compare
+     * @param contextUser the server-side context user (REQUIRED for correct isolation)
+     * @param provider optional request-scoped metadata provider (multi-provider safety)
+     */
+    CompareRecords(input: RecordComparisonInput, contextUser: UserInfo, provider?: IMetadataProvider): Promise<RecordComparisonResult>;
+    /**
+     * The lower-level comparison entry point: given an already-resolved {@link EntityInfo}
+     * (no by-name metadata lookup), load the keyed records and compute the field-delta matrix.
+     *
+     * Callers that already hold the entity and a request-scoped `RunView` (e.g. the duplicate
+     * detector) use this directly via {@link RecordComparisonOptions.RunViewInstance}, avoiding a
+     * redundant metadata resolution. The by-name {@link RecordComparisonEngine.CompareRecords}
+     * resolves the entity and delegates here.
+     *
+     * @param entity the resolved entity to compare records within
+     * @param keys the composite keys to compare (column 0 is the reference/survivor candidate)
+     * @param contextUser the server-side context user (thread for correct isolation)
+     * @param options include-list, an injected RunView, and/or the request-scoped provider
+     */
+    CompareRecordsForEntity(entity: EntityInfo, keys: CompositeKey[], contextUser?: UserInfo, options?: RecordComparisonOptions): Promise<RecordComparisonResult>;
+    /**
+     * Resolves the set of fields to compare: the include-list (case-insensitive) when
+     * supplied, otherwise all non-PK, non-system fields. Sorted name-field → DefaultInView → Sequence.
+     */
+    protected selectFields(entity: EntityInfo, includeFields?: string[]): EntityFieldInfo[];
+    /** True when a field should participate in the comparison. */
+    protected isComparableField(field: EntityFieldInfo, includeSet: Set<string> | null): boolean;
+    /** True for MemberJunction system/internal columns that should not be diffed. */
+    protected isSystemField(fieldName: string): boolean;
+    /** Orders fields name-field first, then DefaultInView, then by Sequence/Name. */
+    protected compareFieldOrder(a: EntityFieldInfo, b: EntityFieldInfo): number;
+    /**
+     * Loads the records via a single read-only RunView OR-ing every supplied key.
+     * Returns plain rows (ResultType 'simple') or null on failure.
+     */
+    protected loadRecords(entity: EntityInfo, keys: CompositeKey[], fields: EntityFieldInfo[], contextUser: UserInfo | undefined, options?: RecordComparisonOptions): Promise<Record<string, RecordFieldValue>[] | null>;
+    /** Builds the field-name select list: PK fields + the compared fields (deduped). */
+    protected buildSelectFieldNames(entity: EntityInfo, fields: EntityFieldInfo[]): string[];
+    /** Builds an OR-ed WHERE clause across all keys, e.g. "(ID='a') OR (ID='b')". */
+    protected buildKeysFilter(keys: CompositeKey[]): string | null;
+    /**
+     * Correlates each input key (by column index) with its loaded row and builds the
+     * per-record value maps. Missing rows yield a record with all-null values.
+     */
+    protected buildRecords(entity: EntityInfo, keys: CompositeKey[], fields: EntityFieldInfo[], rawRecords: Record<string, RecordFieldValue>[]): RecordComparisonRecord[];
+    /** Finds the loaded row whose primary-key values match the supplied composite key. */
+    protected findRowForKey(entity: EntityInfo, key: CompositeKey, rawRecords: Record<string, RecordFieldValue>[]): Record<string, RecordFieldValue> | null;
+    /** True when every PK value on the row equals the key's value (case-insensitive). */
+    protected rowMatchesKey(entity: EntityInfo, key: CompositeKey, row: Record<string, RecordFieldValue>): boolean;
+    /** Extracts the compared-field values from a loaded row (null when row missing). */
+    protected extractFieldValues(fields: EntityFieldInfo[], row: Record<string, RecordFieldValue> | null): Record<string, RecordFieldValue>;
+    /** Produces a readable label: the name-field value when present, else the key string. */
+    protected buildRecordLabel(entity: EntityInfo, key: CompositeKey, row: Record<string, RecordFieldValue> | null): string;
+    /**
+     * Builds the per-field delta matrix from the loaded records. Column 0 is the
+     * reference (survivor candidate); every other cell is compared against it.
+     * Fields where every record's value is empty are dropped.
+     */
+    protected buildFieldDeltas(fields: EntityFieldInfo[], records: RecordComparisonRecord[]): RecordComparisonFieldDelta[];
+    /** Builds the per-record cells for one field, flagging equality against column 0. */
+    protected buildFieldCells(field: EntityFieldInfo, records: RecordComparisonRecord[]): RecordComparisonFieldCell[];
+    /** True when every cell's value is null/empty (such a field carries no signal). */
+    protected allCellsEmpty(cells: RecordComparisonFieldCell[]): boolean;
+    /** Case-insensitive, trimmed equality used for both diff highlighting and PK matching. */
+    protected valuesEqual(a: RecordFieldValue, b: RecordFieldValue): boolean;
+    /** Coerces a loaded value into a comparable scalar; passes scalars through, else null. */
+    protected normalizeValue(value: RecordFieldValue | undefined): RecordFieldValue;
+    /** Builds a failed-shape result. */
+    protected errorResult(entityName: string, message: string): RecordComparisonResult;
+}
+//# sourceMappingURL=RecordComparisonEngine.d.ts.map

package/dist/RecordComparisonEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordComparisonEngine.d.ts","sourceRoot":"","sources":["../src/RecordComparisonEngine.ts"],"names":[],"mappings":"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"}

package/dist/RecordComparisonEngine.js

@@ -0,0 +1,268 @@
+import { LogError, Metadata, RunView } from '@memberjunction/core';
+/**
+ * Framework-agnostic engine that loads a set of records for one entity and computes a
+ * structured field-level delta between them.
+ *
+ * This is the shared comparison primitive used by the LLM reasoning path (it feeds the
+ * "deltas" context to the reasoning provider) and, opportunistically, by the UI
+ * side-by-side comparison panel. It performs a read-only load (`RunView` with
+ * `ResultType: 'simple'` + targeted `Fields`) — it never mutates records.
+ *
+ * No Angular, no Router, no resolver coupling. Server-side: always thread `contextUser`
+ * and (in multi-provider scenarios) the request-scoped `provider`.
+ */
+export class RecordComparisonEngine {
+    /**
+     * Loads the requested records and computes the field-delta matrix.
+     *
+     * @param input the entity, keys, and optional field include-list to compare
+     * @param contextUser the server-side context user (REQUIRED for correct isolation)
+     * @param provider optional request-scoped metadata provider (multi-provider safety)
+     */
+    async CompareRecords(input, contextUser, provider) {
+        const md = provider ?? Metadata.Provider;
+        const entity = md?.EntityByName(input.EntityName);
+        if (!entity) {
+            return this.errorResult(input.EntityName, `Entity '${input.EntityName}' not found in metadata`);
+        }
+        return this.CompareRecordsForEntity(entity, input.Keys, contextUser, {
+            IncludeFields: input.IncludeFields,
+            Provider: provider
+        });
+    }
+    /**
+     * The lower-level comparison entry point: given an already-resolved {@link EntityInfo}
+     * (no by-name metadata lookup), load the keyed records and compute the field-delta matrix.
+     *
+     * Callers that already hold the entity and a request-scoped `RunView` (e.g. the duplicate
+     * detector) use this directly via {@link RecordComparisonOptions.RunViewInstance}, avoiding a
+     * redundant metadata resolution. The by-name {@link RecordComparisonEngine.CompareRecords}
+     * resolves the entity and delegates here.
+     *
+     * @param entity the resolved entity to compare records within
+     * @param keys the composite keys to compare (column 0 is the reference/survivor candidate)
+     * @param contextUser the server-side context user (thread for correct isolation)
+     * @param options include-list, an injected RunView, and/or the request-scoped provider
+     */
+    async CompareRecordsForEntity(entity, keys, contextUser, options) {
+        try {
+            if (!keys || keys.length === 0) {
+                return this.errorResult(entity.Name, 'No keys supplied to compare');
+            }
+            const fields = this.selectFields(entity, options?.IncludeFields);
+            const rawRecords = await this.loadRecords(entity, keys, fields, contextUser, options);
+            if (rawRecords === null) {
+                return this.errorResult(entity.Name, 'Failed to load records for comparison');
+            }
+            const records = this.buildRecords(entity, keys, fields, rawRecords);
+            const deltas = this.buildFieldDeltas(fields, records);
+            return {
+                Success: true,
+                EntityName: entity.Name,
+                Records: records,
+                Fields: deltas
+            };
+        }
+        catch (e) {
+            LogError(e);
+            return this.errorResult(entity.Name, e instanceof Error ? e.message : String(e));
+        }
+    }
+    /**
+     * Resolves the set of fields to compare: the include-list (case-insensitive) when
+     * supplied, otherwise all non-PK, non-system fields. Sorted name-field → DefaultInView → Sequence.
+     */
+    selectFields(entity, includeFields) {
+        const includeSet = includeFields && includeFields.length > 0
+            ? new Set(includeFields.map(f => f.trim().toLowerCase()))
+            : null;
+        const candidates = entity.Fields.filter(f => this.isComparableField(f, includeSet));
+        return candidates.sort((a, b) => this.compareFieldOrder(a, b));
+    }
+    /** True when a field should participate in the comparison. */
+    isComparableField(field, includeSet) {
+        if (includeSet) {
+            return includeSet.has(field.Name.toLowerCase());
+        }
+        if (field.IsPrimaryKey) {
+            return false;
+        }
+        return !this.isSystemField(field.Name);
+    }
+    /** True for MemberJunction system/internal columns that should not be diffed. */
+    isSystemField(fieldName) {
+        return fieldName.startsWith('__mj_');
+    }
+    /** Orders fields name-field first, then DefaultInView, then by Sequence/Name. */
+    compareFieldOrder(a, b) {
+        if (a.IsNameField !== b.IsNameField) {
+            return a.IsNameField ? -1 : 1;
+        }
+        if (a.DefaultInView !== b.DefaultInView) {
+            return a.DefaultInView ? -1 : 1;
+        }
+        const seqA = a.Sequence ?? 0;
+        const seqB = b.Sequence ?? 0;
+        if (seqA !== seqB) {
+            return seqA - seqB;
+        }
+        return a.Name.localeCompare(b.Name);
+    }
+    /**
+     * Loads the records via a single read-only RunView OR-ing every supplied key.
+     * Returns plain rows (ResultType 'simple') or null on failure.
+     */
+    async loadRecords(entity, keys, fields, contextUser, options) {
+        const filter = this.buildKeysFilter(keys);
+        if (!filter) {
+            return null;
+        }
+        // Prefer a caller-supplied RunView (already bound to the request-scoped provider).
+        // Otherwise build one from the provider: concrete MJ providers implement both
+        // IMetadataProvider and IRunViewProvider, so the cast threads it into RunView for
+        // multi-provider safety.
+        const rv = options?.RunViewInstance ?? new RunView(options?.Provider ?? null);
+        const result = await rv.RunView({
+            EntityName: entity.Name,
+            ExtraFilter: filter,
+            Fields: this.buildSelectFieldNames(entity, fields),
+            ResultType: 'simple',
+            MaxRows: keys.length
+        }, contextUser);
+        if (!result.Success) {
+            LogError(`RecordComparisonEngine.loadRecords failed: ${result.ErrorMessage}`);
+            return null;
+        }
+        return result.Results ?? [];
+    }
+    /** Builds the field-name select list: PK fields + the compared fields (deduped). */
+    buildSelectFieldNames(entity, fields) {
+        const names = new Set();
+        for (const pk of entity.PrimaryKeys) {
+            names.add(pk.Name);
+        }
+        for (const f of fields) {
+            names.add(f.Name);
+        }
+        return Array.from(names);
+    }
+    /** Builds an OR-ed WHERE clause across all keys, e.g. "(ID='a') OR (ID='b')". */
+    buildKeysFilter(keys) {
+        const clauses = keys
+            .filter(k => k.HasValue)
+            .map(k => `(${k.ToWhereClause()})`);
+        return clauses.length > 0 ? clauses.join(' OR ') : null;
+    }
+    /**
+     * Correlates each input key (by column index) with its loaded row and builds the
+     * per-record value maps. Missing rows yield a record with all-null values.
+     */
+    buildRecords(entity, keys, fields, rawRecords) {
+        return keys.map((key, columnIndex) => {
+            const row = this.findRowForKey(entity, key, rawRecords);
+            const values = this.extractFieldValues(fields, row);
+            return {
+                ColumnIndex: columnIndex,
+                Key: key,
+                Label: this.buildRecordLabel(entity, key, row),
+                Values: values
+            };
+        });
+    }
+    /** Finds the loaded row whose primary-key values match the supplied composite key. */
+    findRowForKey(entity, key, rawRecords) {
+        return rawRecords.find(row => this.rowMatchesKey(entity, key, row)) ?? null;
+    }
+    /** True when every PK value on the row equals the key's value (case-insensitive). */
+    rowMatchesKey(entity, key, row) {
+        return entity.PrimaryKeys.every(pk => {
+            const keyValue = key.GetValueByFieldName(pk.Name);
+            return this.valuesEqual(row[pk.Name], keyValue);
+        });
+    }
+    /** Extracts the compared-field values from a loaded row (null when row missing). */
+    extractFieldValues(fields, row) {
+        const values = {};
+        for (const f of fields) {
+            values[f.Name] = row ? this.normalizeValue(row[f.Name]) : null;
+        }
+        return values;
+    }
+    /** Produces a readable label: the name-field value when present, else the key string. */
+    buildRecordLabel(entity, key, row) {
+        const nameField = entity.Fields.find(f => f.IsNameField);
+        if (row && nameField) {
+            const v = row[nameField.Name];
+            if (v !== null && v !== undefined && String(v).trim().length > 0) {
+                return String(v);
+            }
+        }
+        return key.Values();
+    }
+    /**
+     * Builds the per-field delta matrix from the loaded records. Column 0 is the
+     * reference (survivor candidate); every other cell is compared against it.
+     * Fields where every record's value is empty are dropped.
+     */
+    buildFieldDeltas(fields, records) {
+        const deltas = [];
+        for (const field of fields) {
+            const cells = this.buildFieldCells(field, records);
+            if (this.allCellsEmpty(cells)) {
+                continue;
+            }
+            deltas.push({
+                FieldName: field.Name,
+                DisplayName: field.DisplayNameOrName,
+                Category: field.Category ?? null,
+                Cells: cells,
+                Differs: cells.some(c => !c.EqualsReference)
+            });
+        }
+        return deltas;
+    }
+    /** Builds the per-record cells for one field, flagging equality against column 0. */
+    buildFieldCells(field, records) {
+        const referenceValue = records.length > 0 ? records[0].Values[field.Name] ?? null : null;
+        return records.map(record => {
+            const value = record.Values[field.Name] ?? null;
+            return {
+                ColumnIndex: record.ColumnIndex,
+                Value: value,
+                EqualsReference: this.valuesEqual(value, referenceValue)
+            };
+        });
+    }
+    /** True when every cell's value is null/empty (such a field carries no signal). */
+    allCellsEmpty(cells) {
+        return cells.every(c => c.Value === null || c.Value === '' || c.Value === undefined);
+    }
+    /** Case-insensitive, trimmed equality used for both diff highlighting and PK matching. */
+    valuesEqual(a, b) {
+        if (a === null || a === undefined) {
+            return b === null || b === undefined;
+        }
+        if (b === null || b === undefined) {
+            return false;
+        }
+        return String(a).trim().toLowerCase() === String(b).trim().toLowerCase();
+    }
+    /** Coerces a loaded value into a comparable scalar; passes scalars through, else null. */
+    normalizeValue(value) {
+        if (value === undefined) {
+            return null;
+        }
+        return value;
+    }
+    /** Builds a failed-shape result. */
+    errorResult(entityName, message) {
+        return {
+            Success: false,
+            ErrorMessage: message,
+            EntityName: entityName,
+            Records: [],
+            Fields: []
+        };
+    }
+}
+//# sourceMappingURL=RecordComparisonEngine.js.map

package/dist/RecordComparisonEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordComparisonEngine.js","sourceRoot":"","sources":["../src/RecordComparisonEngine.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './RecordComparisonEngine.js';
+export * from './operations/RecordComparisonCompareOperation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+CAA+C,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './RecordComparisonEngine.js';
+export * from './operations/RecordComparisonCompareOperation.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+CAA+C,CAAC"}

package/dist/operations/RecordComparisonCompareOperation.d.ts

@@ -0,0 +1,10 @@
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { RecordComparisonCompareOperation, type RecordComparisonCompareInput, type RecordComparisonCompareOutput } from '@memberjunction/core-entities';
+export declare class RecordComparisonCompareServerOperation extends RecordComparisonCompareOperation {
+    protected InternalExecute(input: RecordComparisonCompareInput, provider: IMetadataProvider, user: UserInfo): Promise<RecordComparisonCompareOutput>;
+    /** Builds a {@link CompositeKey} from a wire-form comparison key. */
+    private toCompositeKey;
+}
+/** Tree-shaking anchor — referenced so bundlers retain the `@RegisterClass` registration. */
+export declare function LoadRecordComparisonCompareOperation(): void;
+//# sourceMappingURL=RecordComparisonCompareOperation.d.ts.map

package/dist/operations/RecordComparisonCompareOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordComparisonCompareOperation.d.ts","sourceRoot":"","sources":["../../src/operations/RecordComparisonCompareOperation.ts"],"names":[],"mappings":"AAaA,OAAO,EAAwC,iBAAiB,EAAgB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACvH,OAAO,EACH,gCAAgC,EAChC,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAErC,MAAM,+BAA+B,CAAC;AAGvC,qBACa,sCAAuC,SAAQ,gCAAgC;cACxE,eAAe,CAC3B,KAAK,EAAE,4BAA4B,EACnC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,6BAA6B,CAAC;IAwBzC,qEAAqE;IACrE,OAAO,CAAC,cAAc;CASzB;AAED,6FAA6F;AAC7F,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D"}

package/dist/operations/RecordComparisonCompareOperation.js

@@ -0,0 +1,63 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * @fileoverview Server implementation of the `RecordComparison.Compare` Remote Operation — loads a
+ * set of an entity's records by composite key and computes the field-level delta matrix between them.
+ *
+ * Extends the CodeGen-emitted {@link RecordComparisonCompareOperation} base in
+ * `@memberjunction/core-entities` (`generated/remote_operations.ts` — operation key + typed I/O, from
+ * the `MJ: Remote Operations` row) and supplies the server body via {@link RecordComparisonEngine}.
+ * Registered under `RecordComparison.Compare`; replaces the bespoke `GetRecordComparison` GraphQL
+ * resolver + the hand-written `GraphQLRecordComparisonClient` transport.
+ *
+ * @module @memberjunction/record-comparison
+ */
+import { RegisterClass } from '@memberjunction/global';
+import { BaseRemotableOperation, CompositeKey, KeyValuePair } from '@memberjunction/core';
+import { RecordComparisonCompareOperation, } from '@memberjunction/core-entities';
+import { RecordComparisonEngine } from '../RecordComparisonEngine.js';
+let RecordComparisonCompareServerOperation = class RecordComparisonCompareServerOperation extends RecordComparisonCompareOperation {
+    async InternalExecute(input, provider, user) {
+        if (!input?.EntityName) {
+            throw new Error('EntityName is required');
+        }
+        const engineInput = {
+            EntityName: input.EntityName,
+            Keys: (input.Keys ?? []).map((k) => this.toCompositeKey(k)),
+            IncludeFields: input.IncludeFields,
+        };
+        const result = await new RecordComparisonEngine().CompareRecords(engineInput, user, provider);
+        if (!result.Success) {
+            // Surface as a logical failure on the wrapping RemoteOpResult.
+            throw new Error(result.ErrorMessage ?? 'Record comparison failed');
+        }
+        return {
+            EntityName: result.EntityName,
+            Records: result.Records ?? [],
+            Fields: result.Fields ?? [],
+        };
+    }
+    /** Builds a {@link CompositeKey} from a wire-form comparison key. */
+    toCompositeKey(key) {
+        const pairs = (key.KeyValuePairs ?? []).map((kvp) => {
+            const pair = new KeyValuePair();
+            pair.FieldName = kvp.FieldName;
+            pair.Value = kvp.Value;
+            return pair;
+        });
+        return CompositeKey.FromKeyValuePairs(pairs);
+    }
+};
+RecordComparisonCompareServerOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'RecordComparison.Compare')
+], RecordComparisonCompareServerOperation);
+export { RecordComparisonCompareServerOperation };
+/** Tree-shaking anchor — referenced so bundlers retain the `@RegisterClass` registration. */
+export function LoadRecordComparisonCompareOperation() {
+    // intentionally empty
+}
+//# sourceMappingURL=RecordComparisonCompareOperation.js.map

package/dist/operations/RecordComparisonCompareOperation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordComparisonCompareOperation.js","sourceRoot":"","sources":["../../src/operations/RecordComparisonCompareOperation.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAqB,YAAY,EAAY,MAAM,sBAAsB,CAAC;AACvH,OAAO,EACH,gCAAgC,GAInC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAyB,MAAM,2BAA2B,CAAC;AAGnF,IAAM,sCAAsC,GAA5C,MAAM,sCAAuC,SAAQ,gCAAgC;IAC9E,KAAK,CAAC,eAAe,CAC3B,KAAmC,EACnC,QAA2B,EAC3B,IAAc;QAEd,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC9C,CAAC;QAED,MAAM,WAAW,GAA0B;YACvC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;YAC3D,aAAa,EAAE,KAAK,CAAC,aAAa;SACrC,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,sBAAsB,EAAE,CAAC,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC9F,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAClB,+DAA+D;YAC/D,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,YAAY,IAAI,0BAA0B,CAAC,CAAC;QACvE,CAAC;QAED,OAAO;YACH,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;SAC9B,CAAC;IACN,CAAC;IAED,qEAAqE;IAC7D,cAAc,CAAC,GAAwB;QAC3C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YAChD,MAAM,IAAI,GAAG,IAAI,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YACvB,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,OAAO,YAAY,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;CACJ,CAAA;AAvCY,sCAAsC;IADlD,aAAa,CAAC,sBAAsB,EAAE,0BAA0B,CAAC;GACrD,sCAAsC,CAuClD;;AAED,6FAA6F;AAC7F,MAAM,UAAU,oCAAoC;IAChD,sBAAsB;AAC1B,CAAC"}

package/package.json

@@ -1,10 +1,31 @@
 {
   "name": "@memberjunction/record-comparison",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/record-comparison",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.44.0",
+  "description": "MemberJunction: Framework-agnostic record comparison engine — loads a set of records for one entity and computes a structured field-level delta. Shared by the duplicate-detection reasoning path and the UI side-by-side comparison panel.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/core": "5.44.0",
+    "@memberjunction/core-entities": "5.44.0",
+    "@memberjunction/global": "5.44.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.11",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }