@memberjunction/metadata-sync 5.37.0 → 5.38.0

package/README.md

@@ -195,7 +195,48 @@ The tool is intended for managing business-level metadata such as:
 - Permissions and security settings
 - Any other data that is not reflected **up** from the underlying system database catalogs
 
-For more information about how CodeGen reflects system-level data from the database into the MJ metadata layer, see the [CodeGen documentation](../CodeGen/README.md).
+For more information about how CodeGen reflects system-level data from the database into the MJ metadata layer, see the [CodeGen documentation](../CodeGenLib/README.md).
+
+## Performance: Preloading and Caching During Push
+
+The `push` command preloads existing records and caches files/lookups so the
+per-record sync work avoids redundant DB round-trips and disk I/O.
+
+### 1. Upfront bulk preload (batched `RunViews`)
+
+Before processing records, the push scans every JSON file in the target
+directories (in parallel, with a concurrency cap), collects primary keys
+from records and nested `relatedEntities`, groups them by entity, and
+issues a single filtered `RunView` per entity. This replaces the
+prior per-record existence check with one batched read per entity at
+push start.
+
+### 2. Event-driven in-memory cache (`SyncMetadataEngine` extends `BaseEngine`)
+
+`SyncMetadataEngine` plugs into MJ's `BaseEntity` event bus via `BaseEngine`.
+Saves and deletes performed during the push update the in-memory cache in
+place, so subsequent lookups inside the same run see the new state without
+a re-fetch. The engine overrides `canUseImmediateMutation` to allow this
+in-place update for its own preload configs — the filter is built from
+the preloaded PKs, so updates and deletes stay safe, and newly-created
+records are deliberately added to the cache so later lookups can find them
+within the same push.
+
+### 3. File and lookup caches
+
+- **File cache**: parsed JSON and resolved `@include` output are cached on
+  first read so the validation and sync passes don't reparse. The cache
+  entry for a file is invalidated whenever the push writes that file back
+  to disk.
+- **Lookup cache**: resolved `@lookup` (and `@parent` / `@root`) values are
+  memoized per `(entity, lookup-fields)` key. The cache is indexed by
+  entity so deleting a record invalidates only the affected entries
+  instead of clearing the whole cache. Keys are URI-encoded to prevent
+  collisions when user data contains `=` / `&` / `|`.
+
+> Real-world reductions vary with the size and shape of your metadata
+> tree; expect the biggest wins on syncs that read many records of the
+> same entity (which is the common case).
 
 ## File Structure
 
@@ -1849,8 +1890,8 @@ Processing AI Prompts in demo/ai-prompts
 ## Dependencies
 
 This package depends on:
-- [@memberjunction/core](../MJCore/README.md) -- Core MemberJunction framework (Metadata, RunView, BaseEntity)
-- [@memberjunction/core-entities](../MJCoreEntities/README.md) -- Generated entity subclasses
+- [@memberjunction/core](../MJCore/readme.md) -- Core MemberJunction framework (Metadata, RunView, BaseEntity)
+- [@memberjunction/core-entities](../MJCoreEntities/readme.md) -- Generated entity subclasses
 - [@memberjunction/global](../MJGlobal/README.md) -- Global utilities and class factory
 - [@memberjunction/config](../Config/README.md) -- Configuration management
 - [@memberjunction/sqlserver-dataprovider](../SQLServerDataProvider/README.md) -- SQL Server data access
@@ -1887,3 +1928,104 @@ If you were previously using the standalone `mj-sync` command:
 ## Contributing
 
 See the [MemberJunction Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.
+
+---
+
+## Notes — Push Performance Optimizations (v5.38.x)
+
+The `push` path was substantially reworked to eliminate per-record DB
+round-trips on metadata trees with thousands of records. End-to-end
+measurements on a representative ~36,500-record `metadata/` tree (mostly
+idempotent, including a `metadata/integrations/` dir with 23,789 records):
+
+| Scenario | Pre-optimization | Post-optimization | Speedup |
+|---|---:|---:|---:|
+| Full sync (incl. integrations) | ~6m 49s | **~1m 4s** | **~6.5×** |
+| Partial sync (excluding integrations) | ~1m 37s | **~30.5s** | **~3.2×** |
+
+The changes sit entirely inside the `push` flow; behaviour, configuration,
+and on-disk formats are unchanged.
+
+### What changed
+
+1. **Upfront preloading via `SyncMetadataEngine`** (extends `BaseEngine`).
+   Before processing any file the engine scans every JSON file under each
+   configured entity directory once, collects the set of entity names
+   referenced (including nested `relatedEntities`), and issues a single
+   unfiltered `RunView` per entity through `BaseEngine.Load`. The
+   resulting `BaseEntity` instances live on dynamic per-entity property
+   slots that the sync path consults instead of round-tripping the DB
+   per record.
+
+   Why unfiltered: metadata entities (Actions, Prompts, Agents,
+   Templates, …) are bounded by design. Loading all rows once is faster
+   than computing a giant `WHERE … IN (…)` clause, and it lets
+   `@lookup:` resolution hit the cache even for records that are not
+   directly mentioned in local files. An oversize warning fires if any
+   single entity comes back with more than 100,000 rows so operators
+   notice when something non-metadata-scale slips into a sync workflow.
+
+2. **O(1) PK index on the preload cache.** Each preloaded slot is also
+   indexed into a per-entity `Map<serializedPK, BaseEntity>`. The
+   sync's `loadEntity` path uses this for O(1) hash lookups instead of
+   the previous `Array.find(... serializePrimaryKey(GetAll()))` scan.
+
+   This was the single biggest fix. The naïve `Array.find` was O(N×K)
+   where N = cached rows and K = records being processed. For
+   `MJ: Integration Object Fields` (~100K+ DB rows, ~23,789 records
+   processed) that was ~1.2B comparisons → ~38 minutes. After the Map
+   index the integrations dir alone dropped from 38 minutes to seconds.
+   The index has a self-healing array-scan fallback for entries
+   introduced by `BaseEngine`'s event-driven slot mutations.
+
+3. **Resolved-lookup cache + cached file reads.** Resolved `@lookup:`
+   keys are memoized in a per-engine `Map<lookupKey, ID>`, indexed by
+   entity so the cache invalidates only the affected entries on delete
+   instead of clearing wholesale. The parsed + `@include`-preprocessed
+   contents of every file are also cached, so validation and sync
+   passes don't re-read or re-parse the same file twice. File-cache
+   entries are invalidated at every write site (immediate and deferred
+   writes) so later passes within the same push see fresh contents.
+
+4. **Skip preload for unresolved PK references.** Records whose
+   `primaryKey` still carries an unresolved `@lookup:` / `@parent:` /
+   `@root:` / `@file:` / `@env:` / `@template:` reference are skipped
+   at the preload step — `SyncEngine`'s per-record path resolves them
+   later. Without this guard the preload would inline literal
+   `@lookup:…` strings into a `WHERE ID = '…'` filter and SQL Server
+   would (correctly) reject the cast to uniqueidentifier.
+
+5. **Provider plumbing.** The push flow no longer reaches for
+   `Metadata.Provider` directly during cache and lookup writes —
+   `SyncEngine.getProvider()` is the single entry point. Single-process
+   today; ready for multi-provider scenarios without further surgery.
+
+### Related core fix shipped at the same time
+
+Fixed-width / space-padded character types (`nchar`/`char` on SQL Server;
+`char`/`character`/`bpchar` on PostgreSQL) used to surface their storage
+padding through `BaseEntity.Get`, causing dirty-check to compare e.g.
+`"Input     "` against `"Input"` and false-positive every record as
+dirty. Once preload populated the in-memory comparison this manifested
+as thousands of spurious "updates" per sync (~4,279 on `MJ: Action
+Params` alone).
+
+The fix is in `@memberjunction/core`:
+
+- New `EntityFieldInfo.FixedWidthColumn` getter, delegating to a new
+  `IsFixedWidthStringSQLType` predicate in `@memberjunction/sql-dialect`
+  so the list of fixed-width type names stays in one place per dialect.
+- `EntityField.Value` setter and `BaseEntity.Get` raw fast-path now
+  rtrim string values when `FixedWidthColumn` is true, memoizing back
+  into `_raw` so the trim runs once per field per record.
+
+This is independent of MetadataSync but was exposed by the preload work
+and is required for the "Unchanged" counts to be accurate.
+
+### Observability
+
+`SyncMetadataEngine.drainWarnings()` exposes non-fatal warnings
+collected during preload (malformed `relatedEntities` shapes, oversized
+entities). `PushService` surfaces them through `callbacks.onWarn` so
+they appear in the CLI's standard warning channel alongside everything
+else.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import '@memberjunction/server-bootstrap-lite/mj-class-registrations';
 export { FileBackupManager } from './lib/file-backup-manager.js';
 export { SyncEngine, DeferrableLookupError } from './lib/sync-engine.js';
+export { SyncMetadataEngine } from './lib/sync-metadata-engine.js';
 export type { RecordData, BatchContext } from './lib/sync-engine.js';
 export { BatchContextIndex } from './lib/batch-context-index.js';
 export type { BatchContextStub } from './lib/batch-context-index.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -3,6 +3,7 @@ import '@memberjunction/server-bootstrap-lite/mj-class-registrations';
 // Core library exports
 export { FileBackupManager } from './lib/file-backup-manager.js';
 export { SyncEngine, DeferrableLookupError } from './lib/sync-engine.js';
+export { SyncMetadataEngine } from './lib/sync-metadata-engine.js';
 export { BatchContextIndex } from './lib/batch-context-index.js';
 export { ConfigManager, configManager } from './lib/config-manager.js';
 export { getSyncEngine, resetSyncEngine } from './lib/singleton-manager.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,8DAA8D,CAAC;AAEtE,uBAAuB;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,yBAAyB;AACzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,kBAAkB;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,sBAAsB;AACtB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAIjB,MAAM,UAAU,CAAC;AAElB,qBAAqB;AACrB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,eAAe,EAChB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,8DAA8D,CAAC;AAEtE,uBAAuB;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,yBAAyB;AACzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,kBAAkB;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,sBAAsB;AACtB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAIjB,MAAM,UAAU,CAAC;AAElB,qBAAqB;AACrB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,eAAe,EAChB,MAAM,sBAAsB,CAAC"}

package/dist/lib/config-manager.d.ts

@@ -37,13 +37,21 @@ export declare class ConfigManager extends BaseSingleton<ConfigManager> {
      */
     setOriginalCwd(cwd: string): void;
     /**
-     * Load MemberJunction configuration
+     * Load MemberJunction configuration.
      *
-     * Searches for mj.config.cjs starting from the original working directory
-     * and walking up the directory tree. Caches the result for subsequent calls.
+     * Resolution order:
+     *  1. `process.env.MJ_CONFIG_FILE` — if set to an absolute or repo-relative
+     *     path of a config file (e.g. `mj.config.cjs`), load that file directly.
+     *     Used by the regression archive flow to swap configs between
+     *     `mj sync pull` (source DB) and `mj sync push` (archive DB) without
+     *     touching the filesystem.
+     *  2. Otherwise: cosmiconfig search starting from the original working
+     *     directory, walking up. This is the original behavior.
      *
-     * @param forceReload - Force reload the configuration even if cached
-     * @returns MJConfig object if found, null if not found or invalid
+     * The loaded user config is merged into `DEFAULT_SYNC_CONFIG` so env-var
+     * overrides for database settings continue to apply.
+     *
+     * Result is cached for subsequent calls; pass `forceReload=true` to invalidate.
      */
     loadMJConfig(forceReload?: boolean): MJConfig | null;
     /**

package/dist/lib/config-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../../src/lib/config-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AA+BrC;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,aAAa,CAAC,aAAa,CAAC;IAC7D,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAS;;IAM7B;;OAEG;IACH,WAAkB,QAAQ,IAAI,aAAa,CAE1C;IAED;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAQxB;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;OAQG;IACH,YAAY,CAAC,WAAW,UAAQ,GAAG,QAAQ,GAAG,IAAI;IA0BlD;;;;OAIG;IACH,WAAW,IAAI,QAAQ,GAAG,IAAI;CAM/B;AAGD,eAAO,MAAM,aAAa,eAAyB,CAAC"}
+{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../../src/lib/config-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAiCrC;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,aAAa,CAAC,aAAa,CAAC;IAC7D,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAS;;IAM7B;;OAEG;IACH,WAAkB,QAAQ,IAAI,aAAa,CAE1C;IAED;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAQxB;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,WAAW,UAAQ,GAAG,QAAQ,GAAG,IAAI;IAyClD;;;;OAIG;IACH,WAAW,IAAI,QAAQ,GAAG,IAAI;CAM/B;AAGD,eAAO,MAAM,aAAa,eAAyB,CAAC"}

package/dist/lib/config-manager.js

@@ -10,6 +10,8 @@ import { cosmiconfigSync } from 'cosmiconfig';
 import { mergeConfigs, parseBooleanEnv } from '@memberjunction/config';
 import { BaseSingleton } from '@memberjunction/global';
 import { resolveDbPlatformFromEnv } from '@memberjunction/generic-database-provider';
+import * as fs from 'fs';
+import * as path from 'path';
 const ENV_DB_PLATFORM = resolveDbPlatformFromEnv();
 /**
  * Default configuration for MetadataSync
@@ -78,13 +80,21 @@ export class ConfigManager extends BaseSingleton {
         this.originalCwd = cwd;
     }
     /**
-     * Load MemberJunction configuration
+     * Load MemberJunction configuration.
      *
-     * Searches for mj.config.cjs starting from the original working directory
-     * and walking up the directory tree. Caches the result for subsequent calls.
+     * Resolution order:
+     *  1. `process.env.MJ_CONFIG_FILE` — if set to an absolute or repo-relative
+     *     path of a config file (e.g. `mj.config.cjs`), load that file directly.
+     *     Used by the regression archive flow to swap configs between
+     *     `mj sync pull` (source DB) and `mj sync push` (archive DB) without
+     *     touching the filesystem.
+     *  2. Otherwise: cosmiconfig search starting from the original working
+     *     directory, walking up. This is the original behavior.
      *
-     * @param forceReload - Force reload the configuration even if cached
-     * @returns MJConfig object if found, null if not found or invalid
+     * The loaded user config is merged into `DEFAULT_SYNC_CONFIG` so env-var
+     * overrides for database settings continue to apply.
+     *
+     * Result is cached for subsequent calls; pass `forceReload=true` to invalidate.
      */
     loadMJConfig(forceReload = false) {
         if (this.configLoaded && !forceReload) {
@@ -92,9 +102,25 @@ export class ConfigManager extends BaseSingleton {
         }
         try {
             const explorer = cosmiconfigSync('mj');
-            // Always search from the original working directory
-            const searchPath = this.getOriginalCwd();
-            const result = explorer.search(searchPath);
+            let result;
+            const envOverride = process.env.MJ_CONFIG_FILE;
+            if (envOverride && envOverride.trim()) {
+                // Resolve relative to the original cwd so callers can pass either an
+                // absolute path or a path relative to where the user invoked the CLI.
+                const resolved = path.isAbsolute(envOverride)
+                    ? envOverride
+                    : path.resolve(this.getOriginalCwd(), envOverride);
+                if (!fs.existsSync(resolved)) {
+                    console.error(`MJ_CONFIG_FILE points at "${resolved}" which does not exist; falling back to cosmiconfig search`);
+                    result = explorer.search(this.getOriginalCwd());
+                }
+                else {
+                    result = explorer.load(resolved);
+                }
+            }
+            else {
+                result = explorer.search(this.getOriginalCwd());
+            }
             // Merge user config with DEFAULT_SYNC_CONFIG (user config takes precedence)
             // This ensures environment variables are used for database settings
             // when not explicitly set in the config file

package/dist/lib/config-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/lib/config-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/lib/config-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAErF,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,eAAe,GAAG,wBAAwB,EAAE,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GAAsB;IAC7C,kEAAkE;IAClE,UAAU,EAAE,eAAe,IAAI,WAAW;IAC1C,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,WAAW;IAC1C,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO;QACzB,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QACnC,CAAC,CAAC,CAAC,eAAe,KAAK,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;IACnC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;IACnC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;IACnC,wBAAwB,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;IAC9F,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,SAAS;IAC9C,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;IAC5C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,MAAM;CACnD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,OAAO,aAAc,SAAQ,aAA4B;IAK7D;QACE,KAAK,EAAE,CAAC;QALF,gBAAW,GAAkB,IAAI,CAAC;QAClC,aAAQ,GAAoB,IAAI,CAAC;QACjC,iBAAY,GAAG,KAAK,CAAC;IAI7B,CAAC;IAED;;OAEG;IACI,MAAM,KAAK,QAAQ;QACxB,OAAO,aAAa,CAAC,WAAW,EAAiB,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,0BAA0B;YAC1B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,GAAW;QACxB,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,WAAW,GAAG,KAAK;QAC9B,IAAI,IAAI,CAAC,YAAY,IAAI,CAAC,WAAW,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,MAA0C,CAAC;YAE/C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;YAC/C,IAAI,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;gBACtC,qEAAqE;gBACrE,sEAAsE;gBACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;oBAC3C,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,WAAW,CAAC,CAAC;gBACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7B,OAAO,CAAC,KAAK,CAAC,6BAA6B,QAAQ,4DAA4D,CAAC,CAAC;oBACjH,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;gBAClD,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;YAClD,CAAC;YAED,4EAA4E;YAC5E,oEAAoE;YACpE,6CAA6C;YAC7C,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,mBAAmB,EAAE,UAAU,CAAa,CAAC;YAC1E,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;YACjD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,QAAQ,CAAC"}

package/dist/lib/sync-engine.d.ts

@@ -7,9 +7,10 @@
  * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),
  * manages entity operations, and provides utilities for data transformation.
  */
-import { EntityInfo, BaseEntity, UserInfo } from '@memberjunction/core';
+import { EntityInfo, IMetadataProvider, BaseEntity, UserInfo } from '@memberjunction/core';
 import { EntityConfig } from '../config.js';
 import { BatchContextIndex, BatchContextStub } from './batch-context-index.js';
+import { SyncMetadataEngine } from './sync-metadata-engine.js';
 /** Accepted types for the batchContext parameter (indexed or plain Map). */
 export type BatchContext = BatchContextIndex | Map<string, BaseEntity | BatchContextStub>;
 /**
@@ -109,6 +110,19 @@ export interface RecordData {
 export declare class SyncEngine {
     private metadata;
     private contextUser;
+    private syncMetadataEngine;
+    setMetadataEngine(engine: SyncMetadataEngine): void;
+    getMetadataEngine(): SyncMetadataEngine | null;
+    /**
+     * Returns the metadata provider this engine is using.
+     *
+     * `mj sync` runs as a single-purpose CLI process with one configured
+     * provider per run, so this proxies to the global default (the only
+     * provider the process will ever see). Surfacing it through SyncEngine
+     * keeps callers from reaching for `Metadata.Provider` directly and makes
+     * it obvious which provider the sync is bound to.
+     */
+    getProvider(): IMetadataProvider;
     /**
      * Creates a new SyncEngine instance
      * @param contextUser - The user context for database operations
@@ -201,6 +215,12 @@ export declare class SyncEngine {
      * }
      * ```
      */
+    /**
+     * Build a canonical, collision-safe cache key for a multi-field lookup.
+     * Encodes each field name + value so embedded `=` / `&` / `|` in user
+     * data can't run two distinct lookups into the same key.
+     */
+    private buildLookupCacheKey;
     resolveLookup(entityName: string, lookupFields: Array<{
         fieldName: string;
         fieldValue: string;

package/dist/lib/sync-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/lib/sync-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/lib/sync-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAqB,UAAU,EAAgB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAG5H,OAAO,EAAE,YAAY,EAAgB,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAS5D,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC,CAAC;AAE1F;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,sCAAsC;IACtC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,+CAA+C;IAC/C,SAAgB,YAAY,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAC7E,uCAAuC;IACvC,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,gDAAgD;IAChD,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,EAC5D,aAAa,EAAE,MAAM,EACrB,eAAe,CAAC,EAAE,MAAM;CAY3B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2FAA2F;IAC3F,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,mGAAmG;IACnG,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oCAAoC;IACpC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC/C,mDAAmD;IACnD,IAAI,CAAC,EAAE;QACL,yCAAyC;QACzC,YAAY,EAAE,MAAM,CAAC;QACrB,2CAA2C;QAC3C,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,qEAAqE;IACrE,YAAY,CAAC,EAAE;QACb,qDAAqD;QACrD,MAAM,EAAE,OAAO,CAAC;QAChB,uDAAuD;QACvD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,yEAAyE;QACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,kBAAkB,CAAmC;IAEtD,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAInD,iBAAiB,IAAI,kBAAkB,GAAG,IAAI;IAIrD;;;;;;;;OAQG;IACI,WAAW,IAAI,iBAAiB;IAIvC;;;OAGG;gBACS,WAAW,EAAE,QAAQ;IAKjC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,iBAAiB,CACrB,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI,EACnD,UAAU,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI,EACjD,KAAK,GAAE,MAAU,EACjB,YAAY,CAAC,EAAE,YAAY,EAC3B,mBAAmB,CAAC,EAAE,uBAAuB,EAC7C,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,CAAC;IA6Pf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAarB,aAAa,CACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,EAC5D,UAAU,GAAE,OAAe,EAC3B,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EACtC,YAAY,CAAC,EAAE,YAAY,EAC3B,UAAU,GAAE,OAAe,EAC3B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC;IA+OlB;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IA8B/F;;;;;;OAMG;YACW,gBAAgB;IAe9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM;IAQpC;;;OAGG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;;;;;;OAUG;IACG,gCAAgC,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrF;;;;;;;;;;;OAWG;YACW,gCAAgC;IA6E9C;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIpD;;;;;;;;;;;;;;;;;OAiBG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQjE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA0DjG;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;YACW,8BAA8B;IAuD5C;;;;;;;;;;;;;;;OAeG;YACW,sBAAsB;CA0DrC"}

package/dist/lib/sync-engine.js

@@ -47,11 +47,30 @@ export class DeferrableLookupError extends Error {
  * ```
  */
 export class SyncEngine {
+    setMetadataEngine(engine) {
+        this.syncMetadataEngine = engine;
+    }
+    getMetadataEngine() {
+        return this.syncMetadataEngine;
+    }
+    /**
+     * Returns the metadata provider this engine is using.
+     *
+     * `mj sync` runs as a single-purpose CLI process with one configured
+     * provider per run, so this proxies to the global default (the only
+     * provider the process will ever see). Surfacing it through SyncEngine
+     * keeps callers from reaching for `Metadata.Provider` directly and makes
+     * it obvious which provider the sync is bound to.
+     */
+    getProvider() {
+        return Metadata.Provider; // global-provider-ok: CLI single-process; see class doc
+    }
     /**
      * Creates a new SyncEngine instance
      * @param contextUser - The user context for database operations
      */
     constructor(contextUser) {
+        this.syncMetadataEngine = null;
         this.metadata = new Metadata(); // global-provider-ok: metadata sync operates on the configured provider only
         this.contextUser = contextUser;
     }
@@ -350,13 +369,43 @@ export class SyncEngine {
      * }
      * ```
      */
+    /**
+     * Build a canonical, collision-safe cache key for a multi-field lookup.
+     * Encodes each field name + value so embedded `=` / `&` / `|` in user
+     * data can't run two distinct lookups into the same key.
+     */
+    buildLookupCacheKey(entityName, lookupFields) {
+        const sortedFields = [...lookupFields].sort((a, b) => a.fieldName.localeCompare(b.fieldName));
+        const parts = sortedFields.map(f => {
+            const name = encodeURIComponent(f.fieldName.toLowerCase());
+            const value = encodeURIComponent((f.fieldValue ?? '').toLowerCase());
+            return `${name}=${value}`;
+        });
+        return `${encodeURIComponent(entityName.toLowerCase())}|${parts.join('&')}`;
+    }
     async resolveLookup(entityName, lookupFields, autoCreate = false, createFields = {}, batchContext, allowDefer = false, originalValue) {
+        const lookupCacheKey = this.buildLookupCacheKey(entityName, lookupFields);
+        if (this.syncMetadataEngine) {
+            const cachedId = this.syncMetadataEngine.getCachedLookup(lookupCacheKey);
+            // Use `!== undefined` so legitimately-falsy PK values (empty string, '0')
+            // are still served from cache instead of forcing a re-query.
+            if (cachedId !== undefined) {
+                return cachedId;
+            }
+        }
+        const entityInfo = this.metadata.EntityByName(entityName);
+        if (!entityInfo) {
+            throw new Error(`Entity not found: ${entityName}`);
+        }
         // First check batch context for in-memory entities
         if (batchContext) {
             if (batchContext instanceof BatchContextIndex) {
                 // O(1) indexed lookup
                 const pkValue = batchContext.lookupByFields(entityName, lookupFields);
                 if (pkValue !== undefined) {
+                    if (this.syncMetadataEngine) {
+                        this.syncMetadataEngine.setCachedLookup(lookupCacheKey, pkValue, entityName);
+                    }
                     return pkValue;
                 }
             }
@@ -378,22 +427,43 @@ export class SyncEngine {
                         }
                         if (allMatch) {
                             // Found in batch context, return primary key
-                            const entityInfo = this.metadata.EntityByName(entityName);
-                            if (entityInfo && entityInfo.PrimaryKeys.length > 0) {
+                            if (entityInfo.PrimaryKeys.length > 0) {
                                 const pkeyField = entityInfo.PrimaryKeys[0].Name;
-                                return entity.Get(pkeyField);
+                                const id = entity.Get(pkeyField);
+                                if (this.syncMetadataEngine) {
+                                    this.syncMetadataEngine.setCachedLookup(lookupCacheKey, id, entityName);
+                                }
+                                return id;
                             }
                         }
                     }
                 }
             }
         }
+        // Scan preloaded entities in-memory if preloaded
+        if (this.syncMetadataEngine && this.syncMetadataEngine.isEntityPreloaded(entityName)) {
+            const cachedEntities = this.syncMetadataEngine.getCachedEntities(entityName);
+            for (const cachedEntity of cachedEntities) {
+                let allMatch = true;
+                for (const { fieldName, fieldValue } of lookupFields) {
+                    const entityValue = cachedEntity.Get(fieldName);
+                    const normalizedEntityValue = (entityValue?.toString() || '').toLowerCase().trim();
+                    const normalizedLookupValue = (fieldValue?.toString() || '').toLowerCase().trim();
+                    if (normalizedEntityValue !== normalizedLookupValue) {
+                        allMatch = false;
+                        break;
+                    }
+                }
+                if (allMatch) {
+                    const pkeyField = entityInfo.PrimaryKeys[0].Name;
+                    const id = cachedEntity.Get(pkeyField);
+                    this.syncMetadataEngine.setCachedLookup(lookupCacheKey, id, entityName);
+                    return id;
+                }
+            }
+        }
         // Not found in batch context, check database
         const rv = new RunView();
-        const entityInfo = this.metadata.EntityByName(entityName);
-        if (!entityInfo) {
-            throw new Error(`Entity not found: ${entityName}`);
-        }
         // Build compound filter for all lookup fields
         const filterParts = [];
         for (const { fieldName, fieldValue } of lookupFields) {
@@ -463,6 +533,9 @@ export class SyncEngine {
             if (entityInfo.PrimaryKeys.length > 0) {
                 const pkeyField = entityInfo.PrimaryKeys[0].Name;
                 const id = result.Results[0][pkeyField];
+                if (this.syncMetadataEngine) {
+                    this.syncMetadataEngine.setCachedLookup(lookupCacheKey, id, entityName);
+                }
                 return id;
             }
         }
@@ -508,6 +581,10 @@ export class SyncEngine {
             if (entityInfo.PrimaryKeys.length > 0) {
                 const pkeyField = entityInfo.PrimaryKeys[0].Name;
                 const newId = newEntity.Get(pkeyField);
+                if (this.syncMetadataEngine) {
+                    this.syncMetadataEngine.setCachedLookup(lookupCacheKey, newId, entityName);
+                    this.syncMetadataEngine.addEntityToCache(entityName, newEntity);
+                }
                 return newId;
             }
         }
@@ -791,6 +868,13 @@ export class SyncEngine {
         if (!entityInfo) {
             throw new Error(`Entity not found: ${entityName}`);
         }
+        if (this.syncMetadataEngine && this.syncMetadataEngine.isEntityPreloaded(entityName)) {
+            // O(1) PK lookup against the preload cache. The previous Array.find
+            // + per-entity serializePrimaryKey(GetAll()) was O(N×K) overall and
+            // dominated runtime for entities with large DB-side populations
+            // (Integration Object Fields: 38min → seconds).
+            return this.syncMetadataEngine.findCachedByPrimaryKey(entityName, primaryKey);
+        }
         // First, check if the record exists using RunView to avoid "Error in BaseEntity.Load" messages
         // when records don't exist (which is a normal scenario during sync operations)
         const rv = new RunView();
@@ -821,7 +905,11 @@ export class SyncEngine {
         const compositeKey = new CompositeKey();
         compositeKey.LoadFromSimpleObject(primaryKey);
         const loaded = await entity.InnerLoad(compositeKey);
-        return loaded ? entity : null;
+        const loadedEntity = loaded ? entity : null;
+        if (loadedEntity && this.syncMetadataEngine) {
+            this.syncMetadataEngine.addEntityToCache(entityName, loadedEntity);
+        }
+        return loadedEntity;
     }
     /**
      * Process file content with {@include} references