@fjell/lib-sequelize 4.4.80 → 4.4.82

package/dist/index.js

@@ -941,12 +941,30 @@ var buildSequelizeReference = async (item, referenceDefinition, registry, contex
     );
   }
   if (!registry) {
+    libLogger3.error("Registry not provided for reference processing", {
+      component: "lib-sequelize",
+      subcomponent: "ReferenceBuilder",
+      operation: "buildSequelizeReference",
+      property: referenceDefinition.property,
+      kta: referenceDefinition.kta,
+      column: referenceDefinition.column,
+      suggestion: "Ensure registry is passed to library configuration"
+    });
     throw new Error(
-      `This model definition has a reference definition, but the registry is not present. Reference property: '${referenceDefinition.property}', key types: [${referenceDefinition.kta.join(", ")}], column: '${referenceDefinition.column}'`
+      `This model definition has a reference definition, but the registry is not present. Reference property: '${referenceDefinition.property}', key types: [${referenceDefinition.kta.join(", ")}], column: '${referenceDefinition.column}'. Suggestion: Pass registry to library initialization.`
     );
   }
   const library = registry.get(referenceDefinition.kta);
   if (!library) {
+    libLogger3.error("Referenced library not found in registry", {
+      component: "lib-sequelize",
+      subcomponent: "ReferenceBuilder",
+      operation: "buildSequelizeReference",
+      property: referenceDefinition.property,
+      kta: referenceDefinition.kta,
+      column: referenceDefinition.column,
+      suggestion: `Register a library for [${referenceDefinition.kta.join(", ")}] in the registry`
+    });
     throw new Error(
       `This model definition has a reference definition, but the dependency is not present in registry. Reference property: '${referenceDefinition.property}', missing key type: '${primaryKeyType}', column: '${referenceDefinition.column}'`
     );
@@ -1037,6 +1055,18 @@ var buildSequelizeReference = async (item, referenceDefinition, registry, contex
         referencedItem = await library.operations.get(itemKey);
         context.setCached(itemKey, referencedItem);
       } catch (error) {
+        libLogger3.error("Failed to load reference", {
+          component: "lib-sequelize",
+          subcomponent: "ReferenceBuilder",
+          operation: "buildSequelizeReference",
+          property: referenceDefinition.property,
+          referenceKey: JSON.stringify(itemKey),
+          referencedItemType: primaryKeyType,
+          errorType: error?.constructor?.name,
+          errorMessage: error?.message,
+          errorCode: error?.code || error?.errorInfo?.code,
+          suggestion: "Check referenced item exists, registry is configured, and database connectivity"
+        });
         throw error;
       } finally {
         context.markComplete(itemKey);
@@ -1305,6 +1335,7 @@ import {
   DuplicateError,
   ValidationError
 } from "@fjell/core";
+var logger7 = logger_default.get("sequelize", "errors", "errorHandler");
 function transformSequelizeError(error, itemType, key, modelName, itemData) {
   if (error.code === "23505" || error.original?.code === "23505") {
     const constraint = error.original?.constraint;
@@ -1318,6 +1349,16 @@ function transformSequelizeError(error, itemType, key, modelName, itemData) {
       message = `${itemType} already exists`;
     }
     const field = error.fields ? Object.keys(error.fields)[0] : "unique constraint";
+    logger7.debug("Transformed PostgreSQL unique constraint error to DuplicateError", {
+      component: "lib-sequelize",
+      transformation: "sequelizeErrorHandler",
+      originalError: "PostgreSQL 23505",
+      transformedError: "DuplicateError",
+      itemType,
+      constraint,
+      field,
+      model: modelName
+    });
     return new DuplicateError(message, key, field);
   }
   if (error.name === "SequelizeUniqueConstraintError" || error.code === "ER_DUP_ENTRY") {
@@ -1458,6 +1499,16 @@ function transformSequelizeError(error, itemType, key, modelName, itemData) {
     );
   }
   if (error.name === "SequelizeConnectionError" || error.name === "SequelizeConnectionRefusedError") {
+    logger7.error("Transformed database connection error to BusinessLogicError", {
+      component: "lib-sequelize",
+      transformation: "sequelizeErrorHandler",
+      originalError: error.name,
+      transformedError: "BusinessLogicError",
+      itemType,
+      retryable: true,
+      model: modelName,
+      suggestion: "Check database is running, connection string is correct, and network connectivity"
+    });
     return new BusinessLogicError(
       "Database connection failed",
       "Check database connectivity and try again",
@@ -1466,6 +1517,16 @@ function transformSequelizeError(error, itemType, key, modelName, itemData) {
     );
   }
   if (error.name === "SequelizeTimeoutError") {
+    logger7.error("Transformed database timeout error to BusinessLogicError", {
+      component: "lib-sequelize",
+      transformation: "sequelizeErrorHandler",
+      originalError: "SequelizeTimeoutError",
+      transformedError: "BusinessLogicError",
+      itemType,
+      retryable: true,
+      model: modelName,
+      suggestion: "Reduce query complexity, add indexes, or increase timeout limits"
+    });
     return new BusinessLogicError(
       "Database operation timed out",
       "Try again or simplify the operation",
@@ -1489,7 +1550,7 @@ function transformSequelizeError(error, itemType, key, modelName, itemData) {
 }
 
 // src/metrics/QueryMetrics.ts
-var logger7 = logger_default.get("sequelize", "metrics", "QueryMetrics");
+var logger8 = logger_default.get("sequelize", "metrics", "QueryMetrics");
 var QueryMetrics = class {
   totalQueryCount = 0;
   queriesByModel = /* @__PURE__ */ new Map();
@@ -1504,7 +1565,7 @@ var QueryMetrics = class {
     this.queriesByModel.set(modelName, currentCount + 1);
     if (this.totalQueryCount % this.LOG_INTERVAL === 0) {
       const modelBreakdown = Array.from(this.queriesByModel.entries()).map(([model, count]) => `${model}: ${count}`).join(", ");
-      logger7.debug(
+      logger8.debug(
         `Query execution count: ${this.totalQueryCount} total queries. Breakdown by model: ${modelBreakdown || "none"}`
       );
     }
@@ -1538,7 +1599,7 @@ var QueryMetrics = class {
 var queryMetrics = new QueryMetrics();
 
 // src/ops/all.ts
-var logger8 = logger_default.get("sequelize", "ops", "all");
+var logger9 = logger_default.get("sequelize", "ops", "all");
 var mergeIncludes = (existingIncludes, newIncludes) => {
   const mergedIncludes = [...existingIncludes];
   for (const newInclude of newIncludes) {
@@ -1565,7 +1626,7 @@ var getAllOperation = (models, definition, registry) => {
     async (itemQuery, locations, allOptions) => {
       try {
         const locs = locations ?? [];
-        logger8.debug(`ALL operation called on ${models[0].name} with ${locs.length} location filters: ${locs.map((loc2) => `${loc2.kt}=${loc2.lk}`).join(", ") || "none"}`);
+        logger9.debug(`ALL operation called on ${models[0].name} with ${locs.length} location filters: ${locs.map((loc2) => `${loc2.kt}=${loc2.lk}`).join(", ") || "none"}`);
         const loc = locs;
         const model = models[0];
         let options = buildQuery(itemQuery ?? {}, model, references, registry);
@@ -1590,7 +1651,7 @@ var getAllOperation = (models, definition, registry) => {
             const relationshipInfo = buildRelationshipPath(model, locKey.kt, kta, true);
             if (!relationshipInfo.found) {
               const errorMessage = `Location key '${locKey.kt}' cannot be resolved on model '${model.name}' or through its relationships.`;
-              logger8.error(errorMessage, { locations: loc, kta });
+              logger9.error(errorMessage, { locations: loc, kta });
               throw new Error(errorMessage);
             }
             if (relationshipInfo.isDirect) {
@@ -1601,31 +1662,31 @@ var getAllOperation = (models, definition, registry) => {
           }
           for (const locKey of directLocations) {
             if (locKey.lk === void 0 || locKey.lk == null || locKey.lk === "" || typeof locKey.lk === "object" && Object.keys(locKey.lk).length === 0) {
-              logger8.error(`Location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`, { locKey, locations: loc });
+              logger9.error(`Location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`, { locKey, locations: loc });
               throw new Error(`Location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`);
             }
             const foreignKeyField = locKey.kt + "Id";
             if (options.where[foreignKeyField]) {
-              logger8.debug(`[ALL] Field ${foreignKeyField} already constrained by itemQuery, skipping location constraint to avoid conflicts`);
+              logger9.debug(`[ALL] Field ${foreignKeyField} already constrained by itemQuery, skipping location constraint to avoid conflicts`);
               continue;
             }
-            logger8.trace(`[ALL] Setting direct location where clause: ${foreignKeyField} = ${stringifyJSON(locKey.lk)} (type: ${typeof locKey.lk})`);
+            logger9.trace(`[ALL] Setting direct location where clause: ${foreignKeyField} = ${stringifyJSON(locKey.lk)} (type: ${typeof locKey.lk})`);
             options.where[foreignKeyField] = {
               [Op2.eq]: locKey.lk
             };
           }
           for (const locKey of hierarchicalLocations) {
             if (locKey.lk === void 0 || locKey.lk == null || locKey.lk === "" || typeof locKey.lk === "object" && Object.keys(locKey.lk).length === 0) {
-              logger8.error(`Hierarchical location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`, { locKey, locations: loc });
+              logger9.error(`Hierarchical location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`, { locKey, locations: loc });
               throw new Error(`Hierarchical location key '${locKey.kt}' has invalid lk value: ${stringifyJSON(locKey.lk)}`);
             }
             const relationshipInfo = buildRelationshipPath(model, locKey.kt, kta);
             if (relationshipInfo.found && relationshipInfo.path) {
               if (options.where[relationshipInfo.path]) {
-                logger8.debug(`[ALL] Field ${relationshipInfo.path} already constrained by itemQuery, skipping hierarchical location constraint to avoid conflicts`);
+                logger9.debug(`[ALL] Field ${relationshipInfo.path} already constrained by itemQuery, skipping hierarchical location constraint to avoid conflicts`);
                 continue;
               }
-              logger8.trace(`[ALL] Setting hierarchical location where clause: ${relationshipInfo.path} = ${stringifyJSON(locKey.lk)} (type: ${typeof locKey.lk})`);
+              logger9.trace(`[ALL] Setting hierarchical location where clause: ${relationshipInfo.path} = ${stringifyJSON(locKey.lk)} (type: ${typeof locKey.lk})`);
               options.where[relationshipInfo.path] = {
                 [Op2.eq]: locKey.lk
               };
@@ -1643,7 +1704,7 @@ var getAllOperation = (models, definition, registry) => {
         const effectiveOffset = allOptions?.offset ?? itemQuery?.offset ?? 0;
         const whereFields = options.where ? Object.keys(options.where).join(", ") : "none";
         const includeCount = options.include?.length || 0;
-        logger8.default(
+        logger9.default(
           `All query configured for ${model.name} with where fields: ${whereFields}, includes: ${includeCount}, limit: ${effectiveLimit}, offset: ${effectiveOffset}`
         );
         const countOptions = {
@@ -1656,7 +1717,7 @@ var getAllOperation = (models, definition, registry) => {
         queryMetrics.recordQuery(model.name);
         const countResult = await model.count(countOptions);
         const total = Array.isArray(countResult) ? countResult.length : countResult;
-        logger8.debug(`[ALL] Total count for ${model.name}: ${total}`);
+        logger9.debug(`[ALL] Total count for ${model.name}: ${total}`);
         delete options.limit;
         delete options.offset;
         if (effectiveLimit !== void 0) {
@@ -1666,9 +1727,9 @@ var getAllOperation = (models, definition, registry) => {
           options.offset = effectiveOffset;
         }
         try {
-          logger8.trace(`[ALL] Executing ${model.name}.findAll() with options: ${JSON.stringify(options, null, 2)}`);
+          logger9.trace(`[ALL] Executing ${model.name}.findAll() with options: ${JSON.stringify(options, null, 2)}`);
         } catch {
-          logger8.trace(`[ALL] Executing ${model.name}.findAll() with options containing non-serializable operators (${Object.keys(options.where || {}).length} where conditions)`);
+          logger9.trace(`[ALL] Executing ${model.name}.findAll() with options containing non-serializable operators (${Object.keys(options.where || {}).length} where conditions)`);
         }
         queryMetrics.recordQuery(model.name);
         const matchingItems = await model.findAll(options);
@@ -1686,7 +1747,7 @@ var getAllOperation = (models, definition, registry) => {
           );
           return validateKeys(processedRow, coordinate.kta);
         }));
-        logger8.debug(`[ALL] Returning ${items.length} of ${total} ${model.name} records`);
+        logger9.debug(`[ALL] Returning ${items.length} of ${total} ${model.name} records`);
         return {
           items,
           metadata: {
@@ -1707,7 +1768,7 @@ var getAllOperation = (models, definition, registry) => {
 // src/ops/create.ts
 import { createCreateWrapper, isComKey as isComKey3, isPriKey as isPriKey3 } from "@fjell/core";
 import { validateKeys as validateKeys2 } from "@fjell/core/validation";
-var logger9 = logger_default.get("sequelize", "ops", "create");
+var logger10 = logger_default.get("sequelize", "ops", "create");
 async function validateHierarchicalChain(models, locKey, kta) {
   const locatorIndex = kta.indexOf(locKey.kt);
   if (locatorIndex === -1) {
@@ -1749,8 +1810,8 @@ var getCreateOperation = (models, definition, registry) => {
     coordinate,
     async (item, options) => {
       const constraints = options?.key ? `key: pk=${options.key.pk}, loc=[${isComKey3(options.key) ? options.key.loc.map((l) => `${l.kt}=${l.lk}`).join(", ") : ""}]` : options?.locations ? `locations: ${options.locations.map((loc) => `${loc.kt}=${loc.lk}`).join(", ")}` : "no constraints";
-      logger9.debug(`CREATE operation called on ${models[0].name} with ${constraints}`);
-      logger9.default(`Create configured for ${models[0].name} with ${Object.keys(item).length} item fields`);
+      logger10.debug(`CREATE operation called on ${models[0].name} with ${constraints}`);
+      logger10.default(`Create configured for ${models[0].name} with ${Object.keys(item).length} item fields`);
       const model = models[0];
       const modelAttributes = model.getAttributes();
       let itemData = { ...item };
@@ -1770,9 +1831,18 @@ var getCreateOperation = (models, definition, registry) => {
       }
       if (invalidAttributes.length > 0) {
         const availableAttributes = Object.keys(modelAttributes).join(", ");
-        throw new Error(
-          `Invalid attributes for model '${model.name}': [${invalidAttributes.join(", ")}]. Available attributes: [${availableAttributes}]. Item data: ${JSON.stringify(itemData, null, 2)}`
-        );
+        const errorMessage = `Invalid attributes for model '${model.name}': [${invalidAttributes.join(", ")}]. Available attributes: [${availableAttributes}].`;
+        logger10.error("Create operation failed - invalid attributes", {
+          operation: "create",
+          model: model.name,
+          invalidAttributes,
+          availableAttributes: Object.keys(modelAttributes),
+          providedAttributes: Object.keys(itemData),
+          itemData: JSON.stringify(itemData, null, 2),
+          suggestion: `Remove invalid attributes or add them to the model definition. Valid attributes are: ${availableAttributes}`,
+          coordinate: JSON.stringify(definition.coordinate)
+        });
+        throw new Error(errorMessage + ` Item data: ${JSON.stringify(itemData, null, 2)}`);
       }
       if (options?.key) {
         const key = options.key;
@@ -1788,7 +1858,7 @@ var getCreateOperation = (models, definition, registry) => {
             if (!relationshipInfo.found) {
               const associations = model.associations ? Object.keys(model.associations) : [];
               const errorMessage = `Composite key locator '${locKey.kt}' cannot be resolved on model '${model.name}' or through its relationships. Available associations: [${associations.join(", ")}]. KTA: [${kta.join(", ")}]. Composite key: ${JSON.stringify(comKey, null, 2)}`;
-              logger9.error(errorMessage, { key: comKey, kta, associations });
+              logger10.error(errorMessage, { key: comKey, kta, associations });
               throw new Error(errorMessage);
             }
             if (relationshipInfo.isDirect) {
@@ -1799,7 +1869,7 @@ var getCreateOperation = (models, definition, registry) => {
           }
           for (const locKey of directLocations) {
             if (locKey.lk == null || locKey.lk === "") {
-              logger9.error(`Composite key location '${locKey.kt}' has undefined/null lk value`, { locKey, key: comKey });
+              logger10.error(`Composite key location '${locKey.kt}' has undefined/null lk value`, { locKey, key: comKey });
               throw new Error(`Composite key location '${locKey.kt}' has undefined/null lk value`);
             }
             const foreignKeyField = locKey.kt + "Id";
@@ -1818,7 +1888,7 @@ var getCreateOperation = (models, definition, registry) => {
           if (!relationshipInfo.found) {
             const associations = model.associations ? Object.keys(model.associations) : [];
             const errorMessage = `Location key '${locKey.kt}' cannot be resolved on model '${model.name}' or through its relationships. Available associations: [${associations.join(", ")}]. KTA: [${kta.join(", ")}]. Locations: ${JSON.stringify(options.locations, null, 2)}`;
-            logger9.error(errorMessage, { locations: options.locations, kta, associations });
+            logger10.error(errorMessage, { locations: options.locations, kta, associations });
             throw new Error(errorMessage);
           }
           if (relationshipInfo.isDirect) {
@@ -1829,7 +1899,7 @@ var getCreateOperation = (models, definition, registry) => {
         }
         for (const locKey of directLocations) {
           if (locKey.lk == null || locKey.lk === "") {
-            logger9.error(`Location option '${locKey.kt}' has undefined/null lk value`, { locKey, locations: options.locations });
+            logger10.error(`Location option '${locKey.kt}' has undefined/null lk value`, { locKey, locations: options.locations });
             throw new Error(`Location option '${locKey.kt}' has undefined/null lk value`);
           }
           const foreignKeyField = locKey.kt + "Id";
@@ -1840,14 +1910,64 @@ var getCreateOperation = (models, definition, registry) => {
         }
       }
       try {
-        logger9.trace(`[CREATE] Executing ${model.name}.create() with data: ${stringifyJSON(itemData)}`);
+        logger10.trace(`[CREATE] Executing ${model.name}.create() with data: ${stringifyJSON(itemData)}`);
         queryMetrics.recordQuery(model.name);
         const createdRecord = await model.create(itemData);
-        const processedRecord = await processRow(createdRecord, kta, references || [], aggregations || [], registry, void 0, void 0);
+        let recordToProcess = createdRecord;
+        if (kta.length > 1) {
+          const includesForKey = [];
+          let currentInclude = null;
+          for (let i = kta.length - 1; i > 0; i--) {
+            const relationshipType = kta[i];
+            const relationshipInfo = buildRelationshipPath(model, relationshipType, kta, true);
+            if (relationshipInfo.found && !relationshipInfo.isDirect) {
+              const intermediateType = kta[i - 1];
+              const newInclude = {
+                association: intermediateType,
+                required: false
+              };
+              if (currentInclude) {
+                newInclude.include = [currentInclude];
+              }
+              currentInclude = newInclude;
+            }
+          }
+          if (currentInclude) {
+            includesForKey.push(currentInclude);
+          }
+          if (includesForKey.length > 0) {
+            logger10.debug(`[CREATE] Reloading ${model.name} with includes for key construction`, { includes: includesForKey });
+            queryMetrics.recordQuery(model.name);
+            const reloadedRecord = await model.findByPk(createdRecord.get("id"), {
+              include: includesForKey
+            });
+            if (reloadedRecord) {
+              recordToProcess = reloadedRecord;
+            } else {
+              logger10.warning(`[CREATE] Failed to reload ${model.name} after creation, using original record`);
+            }
+          }
+        }
+        const processedRecord = await processRow(recordToProcess, kta, references || [], aggregations || [], registry, void 0, void 0);
         const result = validateKeys2(processedRecord, kta);
-        logger9.debug(`[CREATE] Created ${model.name} with key: ${result.key ? JSON.stringify(result.key) : `id=${createdRecord.id}`}`);
+        logger10.debug(`[CREATE] Created ${model.name} with key: ${result.key ? JSON.stringify(result.key) : `id=${createdRecord.id}`}`);
         return result;
       } catch (error) {
+        logger10.error("Create operation failed", {
+          operation: "create",
+          model: model.name,
+          itemData: JSON.stringify(itemData, null, 2),
+          options: JSON.stringify(options),
+          errorType: error?.constructor?.name || typeof error,
+          errorMessage: error?.message,
+          errorName: error?.name,
+          sqlError: error?.original?.message,
+          sqlCode: error?.original?.code,
+          constraint: error?.original?.constraint,
+          detail: error?.original?.detail,
+          suggestion: "Check validation rules, unique constraints, foreign keys, required fields, and data types",
+          coordinate: JSON.stringify(definition.coordinate)
+        });
         throw transformSequelizeError(error, kta[0], options?.key, model.name, itemData);
       }
     }
@@ -1857,7 +1977,7 @@ var getCreateOperation = (models, definition, registry) => {
 // src/ops/find.ts
 import { createFindWrapper } from "@fjell/core";
 import { validateKeys as validateKeys3 } from "@fjell/core/validation";
-var logger10 = logger_default.get("sequelize", "ops", "find");
+var logger11 = logger_default.get("sequelize", "ops", "find");
 var getFindOperation = (models, definition, registry) => {
   const { options: { finders, references, aggregations } } = definition;
   return createFindWrapper(
@@ -1867,20 +1987,36 @@ var getFindOperation = (models, definition, registry) => {
         const locs = locations ?? [];
         const params = finderParams ?? {};
         const locationFilters = locs.map((loc) => `${loc.kt}=${loc.lk}`).join(", ") || "none";
-        logger10.debug(
+        logger11.debug(
           `FIND operation called on ${models[0].name} with finder '${finder}' and ${locs.length} location filters: ${locationFilters}`
         );
-        logger10.default(`Find configured for ${models[0].name} using finder '${finder}' with ${Object.keys(params).length} params`);
+        logger11.default(`Find configured for ${models[0].name} using finder '${finder}' with ${Object.keys(params).length} params`);
         if (!finders || !finders[finder]) {
-          logger10.error(`No finders have been defined for this lib`);
-          throw new Error(`No finders found`);
+          const availableFinders = finders ? Object.keys(finders) : [];
+          logger11.error(`No finders defined for library`, {
+            operation: "find",
+            model: models[0]?.name,
+            requestedFinder: finder,
+            availableFinders,
+            suggestion: availableFinders.length > 0 ? `Use one of the available finders: ${availableFinders.join(", ")}` : "Define finders in your library configuration",
+            coordinate: JSON.stringify(definition.coordinate)
+          });
+          throw new Error(`No finders found. ${availableFinders.length > 0 ? `Available finders: ${availableFinders.join(", ")}` : "No finders defined."}`);
         }
         const finderMethod = finders[finder];
         if (!finderMethod) {
-          logger10.error(`Finder %s not found`, finder);
-          throw new Error(`Finder ${finder} not found`);
+          const availableFinders = Object.keys(finders);
+          logger11.error(`Finder not found`, {
+            operation: "find",
+            model: models[0]?.name,
+            requestedFinder: finder,
+            availableFinders,
+            suggestion: `Use one of: ${availableFinders.join(", ")}`,
+            coordinate: JSON.stringify(definition.coordinate)
+          });
+          throw new Error(`Finder '${finder}' not found. Available finders: ${availableFinders.join(", ")}`);
         }
-        logger10.trace(`[FIND] Executing finder '${finder}' on ${models[0].name} with params: ${stringifyJSON(params)}, locations: ${stringifyJSON(locs)}, options: ${stringifyJSON(findOptions)}`);
+        logger11.trace(`[FIND] Executing finder '${finder}' on ${models[0].name} with params: ${stringifyJSON(params)}, locations: ${stringifyJSON(locs)}, options: ${stringifyJSON(findOptions)}`);
         const finderResult = await finderMethod(params, locs, findOptions);
         const processItems = async (items) => {
           return await Promise.all(items.map(async (row) => {
@@ -1892,7 +2028,7 @@ var getFindOperation = (models, definition, registry) => {
         if (isOptInResult) {
           const optInResult = finderResult;
           const processedResults2 = optInResult.items && optInResult.items.length > 0 ? await processItems(optInResult.items) : [];
-          logger10.debug(`[FIND] Finder opted-in, found ${processedResults2.length} ${models[0].name} records using finder '${finder}' (total: ${optInResult.metadata.total})`);
+          logger11.debug(`[FIND] Finder opted-in, found ${processedResults2.length} ${models[0].name} records using finder '${finder}' (total: ${optInResult.metadata.total})`);
           return {
             items: processedResults2,
             metadata: optInResult.metadata
@@ -1900,7 +2036,7 @@ var getFindOperation = (models, definition, registry) => {
         }
         const results = finderResult;
         const processedResults = results && results.length > 0 ? await processItems(results) : [];
-        logger10.debug(`[FIND] Legacy finder, found ${processedResults.length} ${models[0].name} records using finder '${finder}'`);
+        logger11.debug(`[FIND] Legacy finder, found ${processedResults.length} ${models[0].name} records using finder '${finder}'`);
         return {
           items: processedResults,
           metadata: {
@@ -1911,7 +2047,7 @@ var getFindOperation = (models, definition, registry) => {
           }
         };
       } catch (error) {
-        logger10.error("Error in find operation", {
+        logger11.error("Error in find operation", {
           finder,
           finderParams,
           locations,
@@ -1943,7 +2079,7 @@ import {
   validateKeys as validateKeys4
 } from "@fjell/core";
 import { NotFoundError } from "@fjell/core";
-var logger11 = logger_default.get("sequelize", "ops", "get");
+var logger12 = logger_default.get("sequelize", "ops", "get");
 var processCompositeKey = (comKey, model, kta) => {
   const where = { id: comKey.pk };
   const includes = [];
@@ -1951,7 +2087,7 @@ var processCompositeKey = (comKey, model, kta) => {
     const relationshipInfo = buildRelationshipPath(model, locator.kt, kta);
     if (!relationshipInfo.found) {
       const errorMessage = `Composite key locator '${locator.kt}' cannot be resolved on model '${model.name}' or through its relationships. Key type array: [${kta.join(", ")}], Composite key: ${stringifyJSON(comKey)}, Available associations: [${Object.keys(model.associations || {}).join(", ")}]`;
-      logger11.error(errorMessage, { key: comKey, kta });
+      logger12.error(errorMessage, { key: comKey, kta });
       throw new Error(errorMessage);
     }
     if (relationshipInfo.path) {
@@ -1978,12 +2114,12 @@ var getGetOperation = (models, definition, registry) => {
     async (key) => {
       try {
         if (!isValidItemKey(key)) {
-          logger11.error("Key for Get is not a valid ItemKey: %j", key);
+          logger12.error("Key for Get is not a valid ItemKey: %j", key);
           throw new Error("Key for Get is not a valid ItemKey");
         }
         const keyDescription = isPriKey4(key) ? `primary key: pk=${key.pk}` : `composite key: pk=${key.pk}, loc=[${key.loc.map((l) => `${l.kt}=${l.lk}`).join(", ")}]`;
-        logger11.debug(`GET operation called on ${models[0].name} with ${keyDescription}`);
-        logger11.default(`Get configured for ${models[0].name} with ${isPriKey4(key) ? "primary" : "composite"} key`);
+        logger12.debug(`GET operation called on ${models[0].name} with ${keyDescription}`);
+        logger12.default(`Get configured for ${models[0].name} with ${isPriKey4(key) ? "primary" : "composite"} key`);
         const itemKey = key;
         const model = models[0];
         let item;
@@ -1997,7 +2133,7 @@ var getGetOperation = (models, definition, registry) => {
           const aggResult = addAggregationIncludes(options, model, aggregations || []);
           includedAggregations = aggResult.includedAggregations;
           options = aggResult.options;
-          logger11.trace(`[GET] Executing ${model.name}.findByPk() with pk: ${itemKey.pk}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
+          logger12.trace(`[GET] Executing ${model.name}.findByPk() with pk: ${itemKey.pk}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
           queryMetrics.recordQuery(model.name);
           item = options.include && options.include.length > 0 ? await model.findByPk(itemKey.pk, { include: options.include }) : await model.findByPk(itemKey.pk);
         } else if (isComKey4(itemKey)) {
@@ -2010,8 +2146,8 @@ var getGetOperation = (models, definition, registry) => {
             const aggResult = addAggregationIncludes(options, model, aggregations || []);
             includedAggregations = aggResult.includedAggregations;
             options = aggResult.options;
-            logger11.debug(`[GET] Empty loc array detected - finding by primary key across all locations: ${comKey.pk}`);
-            logger11.trace(`[GET] Executing ${model.name}.findByPk() with pk: ${comKey.pk}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
+            logger12.debug(`[GET] Empty loc array detected - finding by primary key across all locations: ${comKey.pk}`);
+            logger12.trace(`[GET] Executing ${model.name}.findByPk() with pk: ${comKey.pk}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
             queryMetrics.recordQuery(model.name);
             item = options.include && options.include.length > 0 ? await model.findByPk(comKey.pk, { include: options.include }) : await model.findByPk(comKey.pk);
           } else {
@@ -2022,8 +2158,8 @@ var getGetOperation = (models, definition, registry) => {
             const aggResult = addAggregationIncludes(queryOptions, model, aggregations || []);
             includedAggregations = aggResult.includedAggregations;
             queryOptions = aggResult.options;
-            logger11.default("Composite key query", { queryOptions });
-            logger11.trace(`[GET] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
+            logger12.default("Composite key query", { queryOptions });
+            logger12.trace(`[GET] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}, ${includedReferences.length} reference includes, and ${includedAggregations.length} aggregation includes`);
             queryMetrics.recordQuery(model.name);
             item = await model.findOne(queryOptions);
           }
@@ -2037,7 +2173,7 @@ var getGetOperation = (models, definition, registry) => {
         }
         const currentContext = contextManager.getCurrentContext();
         const result = validateKeys4(await processRow(item, kta, references || [], aggregations || [], registry, currentContext, includedAggregations, includedReferences), kta);
-        logger11.debug(`[GET] Retrieved ${model.name} with key: ${result.key ? JSON.stringify(result.key) : `id=${item.id}`}`);
+        logger12.debug(`[GET] Retrieved ${model.name} with key: ${result.key ? JSON.stringify(result.key) : `id=${item.id}`}`);
         return result;
       } catch (error) {
         if (error instanceof NotFoundError) throw error;
@@ -2049,21 +2185,21 @@ var getGetOperation = (models, definition, registry) => {
 
 // src/ops/one.ts
 import { createOneWrapper } from "@fjell/core";
-var logger12 = logger_default.get("sequelize", "ops", "one");
+var logger13 = logger_default.get("sequelize", "ops", "one");
 var getOneOperation = (models, definition, registry) => {
   return createOneWrapper(
     definition.coordinate,
     async (itemQuery, locations) => {
       const locs = locations ?? [];
-      logger12.debug(`ONE operation called on ${models[0].name} with ${locs.length} location filters: ${locs.map((loc) => `${loc.kt}=${loc.lk}`).join(", ") || "none"}`);
-      logger12.default(`One configured for ${models[0].name} delegating to all operation`);
+      logger13.debug(`ONE operation called on ${models[0].name} with ${locs.length} location filters: ${locs.map((loc) => `${loc.kt}=${loc.lk}`).join(", ") || "none"}`);
+      logger13.default(`One configured for ${models[0].name} delegating to all operation`);
       const result = await getAllOperation(models, definition, registry)(itemQuery ?? {}, locs, { limit: 1 });
       if (result.items.length > 0) {
         const item = result.items[0];
-        logger12.debug(`[ONE] Found ${models[0].name} record with key: ${item.key ? JSON.stringify(item.key) : "unknown"}`);
+        logger13.debug(`[ONE] Found ${models[0].name} record with key: ${item.key ? JSON.stringify(item.key) : "unknown"}`);
         return item;
       } else {
-        logger12.debug(`[ONE] No ${models[0].name} record found`);
+        logger13.debug(`[ONE] No ${models[0].name} record found`);
         return null;
       }
     }
@@ -2073,7 +2209,7 @@ var getOneOperation = (models, definition, registry) => {
 // src/ops/remove.ts
 import { abbrevIK, isComKey as isComKey5, isPriKey as isPriKey5, isValidItemKey as isValidItemKey2, createRemoveWrapper } from "@fjell/core";
 import { NotFoundError as NotFoundError2 } from "@fjell/core";
-var logger13 = logger_default.get("sequelize", "ops", "remove");
+var logger14 = logger_default.get("sequelize", "ops", "remove");
 var processCompositeKey2 = (comKey, model, kta) => {
   const where = { id: comKey.pk };
   const includes = [];
@@ -2081,7 +2217,7 @@ var processCompositeKey2 = (comKey, model, kta) => {
     const relationshipInfo = buildRelationshipPath(model, locator.kt, kta);
     if (!relationshipInfo.found) {
       const errorMessage = `Composite key locator '${locator.kt}' cannot be resolved on model '${model.name}' or through its relationships.`;
-      logger13.error(errorMessage, { key: comKey, kta });
+      logger14.error(errorMessage, { key: comKey, kta });
       throw new Error(errorMessage);
     }
     if (relationshipInfo.path) {
@@ -2108,25 +2244,25 @@ var getRemoveOperation = (models, definition, _registry) => {
     async (key) => {
       try {
         if (!isValidItemKey2(key)) {
-          logger13.error("Key for Remove is not a valid ItemKey: %j", key);
+          logger14.error("Key for Remove is not a valid ItemKey: %j", key);
           throw new Error("Key for Remove is not a valid ItemKey");
         }
         const keyDescription = isPriKey5(key) ? `primary key: pk=${key.pk}` : `composite key: pk=${key.pk}, loc=[${key.loc.map((l) => `${l.kt}=${l.lk}`).join(", ")}]`;
-        logger13.debug(`REMOVE operation called on ${models[0].name} with ${keyDescription}`);
-        logger13.default(`Remove configured for ${models[0].name} with ${isPriKey5(key) ? "primary" : "composite"} key`);
+        logger14.debug(`REMOVE operation called on ${models[0].name} with ${keyDescription}`);
+        logger14.default(`Remove configured for ${models[0].name} with ${isPriKey5(key) ? "primary" : "composite"} key`);
         const model = models[0];
         let item;
         let returnItem;
-        logger13.debug("remove: %s", abbrevIK(key));
+        logger14.debug("remove: %s", abbrevIK(key));
         if (isPriKey5(key)) {
-          logger13.debug(`[REMOVE] Executing ${model.name}.findByPk() with pk: ${key.pk}`);
+          logger14.debug(`[REMOVE] Executing ${model.name}.findByPk() with pk: ${key.pk}`);
           queryMetrics.recordQuery(model.name);
           item = await model.findByPk(key.pk);
         } else if (isComKey5(key)) {
           const comKey = key;
           const queryOptions = processCompositeKey2(comKey, model, kta);
-          logger13.default(`Remove composite key query for ${model.name} with where fields: ${queryOptions.where ? Object.keys(queryOptions.where).join(", ") : "none"}`);
-          logger13.debug(`[REMOVE] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}`);
+          logger14.default(`Remove composite key query for ${model.name} with where fields: ${queryOptions.where ? Object.keys(queryOptions.where).join(", ") : "none"}`);
+          logger14.debug(`[REMOVE] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}`);
           queryMetrics.recordQuery(model.name);
           item = await model.findOne(queryOptions);
         }
@@ -2146,14 +2282,14 @@ var getRemoveOperation = (models, definition, _registry) => {
           if (model.getAttributes().deletedAt) {
             item.deletedAt = /* @__PURE__ */ new Date();
           }
-          logger13.debug(`[REMOVE] Executing ${model.name}.save() for soft delete`);
+          logger14.debug(`[REMOVE] Executing ${model.name}.save() for soft delete`);
           queryMetrics.recordQuery(model.name);
           await item?.save();
           returnItem = item?.get({ plain: true });
           returnItem = addKey(item, returnItem, kta);
           returnItem = populateEvents(returnItem);
         } else if (options.deleteOnRemove) {
-          logger13.debug(`[REMOVE] Executing ${model.name}.destroy() for hard delete`);
+          logger14.debug(`[REMOVE] Executing ${model.name}.destroy() for hard delete`);
           queryMetrics.recordQuery(model.name);
           await item?.destroy();
           returnItem = item?.get({ plain: true });
@@ -2162,7 +2298,7 @@ var getRemoveOperation = (models, definition, _registry) => {
         } else {
           throw new Error("No deletedAt or isDeleted attribute found in model, and deleteOnRemove is not set");
         }
-        logger13.debug(`[REMOVE] Removed ${model.name} with key: ${returnItem.key ? JSON.stringify(returnItem.key) : `id=${item.id}`}`);
+        logger14.debug(`[REMOVE] Removed ${model.name} with key: ${returnItem.key ? JSON.stringify(returnItem.key) : `id=${item.id}`}`);
         const { references } = options;
         if (references && references.length > 0) {
           returnItem = addRefsToSequelizeItem(returnItem, references);
@@ -2186,7 +2322,7 @@ import {
 import { validateKeys as validateKeys5 } from "@fjell/core/validation";
 import { NotFoundError as NotFoundError3 } from "@fjell/core";
 import { Op as Op3 } from "sequelize";
-var logger14 = logger_default.get("sequelize", "ops", "update");
+var logger15 = logger_default.get("sequelize", "ops", "update");
 var mergeIncludes2 = (existingIncludes, newIncludes) => {
   const mergedIncludes = [...existingIncludes];
   for (const newInclude of newIncludes) {
@@ -2218,15 +2354,15 @@ var getUpdateOperation = (models, definition, registry) => {
           );
         }
         const keyDescription = isPriKey6(key) ? `primary key: pk=${key.pk}` : `composite key: pk=${key.pk}, loc=[${key.loc.map((l) => `${l.kt}=${l.lk}`).join(", ")}]`;
-        logger14.debug(`UPDATE operation called on ${models[0].name} with ${keyDescription}`, { options });
+        logger15.debug(`UPDATE operation called on ${models[0].name} with ${keyDescription}`, { options });
         const { coordinate } = definition;
         const { kta } = coordinate;
-        logger14.debug("update: %s, %j", abbrevIK2(key), item);
+        logger15.debug("update: %s, %j", abbrevIK2(key), item);
         const model = models[0];
         let response;
         if (isPriKey6(key)) {
           const priKey = key;
-          logger14.trace(`[UPDATE] Executing ${model.name}.findByPk() with pk: ${priKey.pk}`);
+          logger15.trace(`[UPDATE] Executing ${model.name}.findByPk() with pk: ${priKey.pk}`);
           queryMetrics.recordQuery(model.name);
           response = await model.findByPk(priKey.pk);
         } else if (isComKey6(key)) {
@@ -2237,7 +2373,7 @@ var getUpdateOperation = (models, definition, registry) => {
             const relationshipInfo = buildRelationshipPath(model, locator.kt, kta, true);
             if (!relationshipInfo.found) {
               const errorMessage = `Composite key locator '${locator.kt}' cannot be resolved on model '${model.name}' or through its relationships.`;
-              logger14.error(errorMessage, { key: comKey, kta });
+              logger15.error(errorMessage, { key: comKey, kta });
               throw new Error(errorMessage);
             }
             if (relationshipInfo.isDirect) {
@@ -2256,8 +2392,8 @@ var getUpdateOperation = (models, definition, registry) => {
           if (additionalIncludes.length > 0) {
             queryOptions.include = mergeIncludes2([], additionalIncludes);
           }
-          logger14.default(`Update composite key query for ${model.name} with where fields: ${queryOptions.where ? Object.keys(queryOptions.where).join(", ") : "none"}`);
-          logger14.trace(`[UPDATE] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}`);
+          logger15.default(`Update composite key query for ${model.name} with where fields: ${queryOptions.where ? Object.keys(queryOptions.where).join(", ") : "none"}`);
+          logger15.trace(`[UPDATE] Executing ${model.name}.findOne() with options: ${stringifyJSON(queryOptions)}`);
           queryMetrics.recordQuery(model.name);
           response = await model.findOne(queryOptions);
         }
@@ -2277,14 +2413,14 @@ var getUpdateOperation = (models, definition, registry) => {
         if (aggregations && aggregations.length > 0) {
           updateProps = removeAggsFromItem(updateProps, aggregations);
         }
-        logger14.default(`Update found ${model.name} record to modify`);
-        logger14.default(`Update properties configured: ${Object.keys(updateProps).join(", ")}`);
-        logger14.trace(`[UPDATE] Executing ${model.name}.update() with properties: ${stringifyJSON(updateProps)}`);
+        logger15.default(`Update found ${model.name} record to modify`);
+        logger15.default(`Update properties configured: ${Object.keys(updateProps).join(", ")}`);
+        logger15.trace(`[UPDATE] Executing ${model.name}.update() with properties: ${stringifyJSON(updateProps)}`);
         queryMetrics.recordQuery(model.name);
         response = await response.update(updateProps);
         const processedItem = await processRow(response, kta, references || [], aggregations || [], registry, void 0, void 0);
         const returnItem = validateKeys5(processedItem, kta);
-        logger14.debug(`[UPDATE] Updated ${model.name} with key: ${returnItem.key ? JSON.stringify(returnItem.key) : `id=${response.id}`}`);
+        logger15.debug(`[UPDATE] Updated ${model.name} with key: ${returnItem.key ? JSON.stringify(returnItem.key) : `id=${response.id}`}`);
         return returnItem;
       } catch (error) {
         if (error instanceof NotFoundError3) throw error;
@@ -2296,7 +2432,7 @@ var getUpdateOperation = (models, definition, registry) => {
 
 // src/ops/upsert.ts
 import { createUpsertWrapper, isValidItemKey as isValidItemKey3, NotFoundError as NotFoundError4 } from "@fjell/core";
-var logger15 = logger_default.get("sequelize", "ops", "upsert");
+var logger16 = logger_default.get("sequelize", "ops", "upsert");
 var getUpsertOperation = (models, definition, registry) => {
   const get = getGetOperation(models, definition, registry);
   const update = getUpdateOperation(models, definition, registry);
@@ -2305,31 +2441,50 @@ var getUpsertOperation = (models, definition, registry) => {
     definition.coordinate,
     async (key, item, locations, options) => {
       if (!isValidItemKey3(key)) {
-        logger15.error("Key for Upsert is not a valid ItemKey: %j", key);
-        throw new Error(`Key for Upsert is not a valid ItemKey: ${stringifyJSON(key)}`);
+        logger16.error("Invalid key for upsert operation", {
+          operation: "upsert",
+          model: models[0]?.name,
+          key: stringifyJSON(key),
+          keyType: typeof key,
+          reason: "Key validation failed",
+          suggestion: "Ensure key has valid PriKey or ComKey structure",
+          coordinate: JSON.stringify(definition.coordinate)
+        });
+        throw new Error(`Invalid key for upsert operation: ${stringifyJSON(key)}. Expected valid PriKey or ComKey structure.`);
       }
-      logger15.debug(`[UPSERT] Attempting upsert with key: ${stringifyJSON(key)}`, { options });
+      logger16.debug(`[UPSERT] Attempting upsert with key: ${stringifyJSON(key)}`, { options });
       let resultItem = null;
       try {
-        logger15.debug(`[UPSERT] Retrieving item by key: ${stringifyJSON(key)}`);
+        logger16.debug(`[UPSERT] Retrieving item by key: ${stringifyJSON(key)}`);
         resultItem = await get(key);
       } catch (error) {
         const isNotFound = error instanceof NotFoundError4 || error?.name === "NotFoundError" || error?.errorInfo?.code === "NOT_FOUND";
         if (isNotFound) {
-          logger15.debug(`[UPSERT] Item not found, creating new item with key: ${stringifyJSON(key)}, errorType: ${error?.name}, errorCode: ${error?.errorInfo?.code}`);
+          logger16.debug(`[UPSERT] Item not found, creating new item with key: ${stringifyJSON(key)}, errorType: ${error?.name}, errorCode: ${error?.errorInfo?.code}`);
           const createOptions3 = locations ? { locations } : { key };
           resultItem = await create(item, createOptions3);
         } else {
-          logger15.error(`[UPSERT] Unexpected error during get operation`, { error: error?.message, name: error?.name, code: error?.errorInfo?.code });
+          logger16.error(`[UPSERT] Unexpected error during get operation`, {
+            operation: "upsert",
+            phase: "get-existing",
+            model: models[0]?.name,
+            key: stringifyJSON(key),
+            errorType: error?.constructor?.name || typeof error,
+            errorMessage: error?.message,
+            errorName: error?.name,
+            errorCode: error?.errorInfo?.code,
+            suggestion: "Check database connectivity, permissions, and key validity",
+            coordinate: JSON.stringify(definition.coordinate)
+          });
           throw error;
         }
       }
       if (!resultItem) {
         throw new Error(`Failed to retrieve or create item for key: ${stringifyJSON(key)}`);
       }
-      logger15.debug(`[UPSERT] Updating item with properties, key: ${stringifyJSON(key)}`, { options });
+      logger16.debug(`[UPSERT] Updating item with properties, key: ${stringifyJSON(key)}`, { options });
       resultItem = await update(resultItem.key, item, options);
-      logger15.debug(`[UPSERT] Item upserted successfully: ${stringifyJSON(resultItem)}`);
+      logger16.debug(`[UPSERT] Item upserted successfully: ${stringifyJSON(resultItem)}`);
       return resultItem;
     }
   );
@@ -2358,9 +2513,9 @@ var createOperations = (models, coordinate, registry, options) => {
 };
 
 // src/SequelizeLibrary.ts
-var logger16 = logger_default.get("SequelizeLibrary");
+var logger17 = logger_default.get("SequelizeLibrary");
 var createSequelizeLibrary = (registry, coordinate, models, options) => {
-  logger16.debug("createSequelizeLibrary", { coordinate, models, registry, options });
+  logger17.debug("createSequelizeLibrary", { coordinate, models, registry, options });
   const operations = createOperations(models, coordinate, registry, options);
   const wrappedOperations = Library3.wrapOperations(operations, options, coordinate, registry);
   const libLibrary = Library3.createLibrary(registry, coordinate, wrappedOperations, options);
@@ -2374,10 +2529,10 @@ var isSequelizeLibrary = (library) => {
 };
 
 // src/SequelizeLibraryFactory.ts
-var logger17 = logger_default.get("InstanceFactory");
+var logger18 = logger_default.get("InstanceFactory");
 var createSequelizeLibraryFactory = (models, options) => {
   return (coordinate, context) => {
-    logger17.debug("Creating Sequelize instance", {
+    logger18.debug("Creating Sequelize instance", {
       coordinate,
       registry: context.registry,
       models: models.map((m) => m.name),
@@ -2422,9 +2577,9 @@ __export(primary_exports, {
 
 // src/primary/SequelizeLibrary.ts
 import { Primary } from "@fjell/lib";
-var logger18 = logger_default.get("lib-sequelize", "primary", "library");
+var logger19 = logger_default.get("lib-sequelize", "primary", "library");
 function createSequelizeLibrary3(keyType, models, libOptions = {}, scopes = [], registry) {
-  logger18.debug("createSequelizeLibrary", { keyType, models, libOptions, scopes });
+  logger19.debug("createSequelizeLibrary", { keyType, models, libOptions, scopes });
   const coordinate = createCoordinate([keyType], scopes);
   const options = createOptions2(libOptions);
   const operations = createOperations(models, coordinate, registry, options);