@fjell/core 4.4.47 → 4.4.49

package/dist/index.js

@@ -64,11 +64,23 @@ var Dictionary = class _Dictionary {
   }
 };
 
+// src/Coordinate.ts
+var logger2 = logger_default.get("Coordinate");
+var createCoordinate = (kta, scopes = []) => {
+  const ktArray = Array.isArray(kta) ? kta : [kta];
+  const toString = () => {
+    logger2.debug("toString", { kta, scopes });
+    return `${ktArray.join(", ")} - ${scopes.join(", ")}`;
+  };
+  logger2.debug("createCoordinate", { kta: ktArray, scopes, toString });
+  return { kta: ktArray, scopes, toString };
+};
+
 // src/item/IFactory.ts
 import deepmerge from "deepmerge";
 
 // src/key/KUtils.ts
-var logger2 = logger_default.get("KUtils");
+var logger3 = logger_default.get("KUtils");
 var normalizeKeyValue = (value) => {
   return String(value);
 };
@@ -96,15 +108,15 @@ var createNormalizedHashFunction = () => {
   };
 };
 var isPriKeyEqualNormalized = (a, b) => {
-  logger2.trace("isPriKeyEqualNormalized", { a, b });
+  logger3.trace("isPriKeyEqualNormalized", { a, b });
   return a && b && normalizeKeyValue(a.pk) === normalizeKeyValue(b.pk) && a.kt === b.kt;
 };
 var isLocKeyEqualNormalized = (a, b) => {
-  logger2.trace("isLocKeyEqualNormalized", { a, b });
+  logger3.trace("isLocKeyEqualNormalized", { a, b });
   return a && b && normalizeKeyValue(a.lk) === normalizeKeyValue(b.lk) && a.kt === b.kt;
 };
 var isComKeyEqualNormalized = (a, b) => {
-  logger2.trace("isComKeyEqualNormalized", { a, b });
+  logger3.trace("isComKeyEqualNormalized", { a, b });
   if (a && b && isPriKeyEqualNormalized({ kt: a.kt, pk: a.pk }, { kt: b.kt, pk: b.pk })) {
     if (a.loc.length === b.loc.length) {
       for (let i = 0; i < a.loc.length; i++) {
@@ -121,7 +133,7 @@ var isComKeyEqualNormalized = (a, b) => {
   }
 };
 var isItemKeyEqualNormalized = (a, b) => {
-  logger2.trace("isItemKeyEqualNormalized", { a, b });
+  logger3.trace("isItemKeyEqualNormalized", { a, b });
   if (isComKey(a) && isComKey(b)) {
     return isComKeyEqualNormalized(a, b);
   } else if (isPriKey(a) && isPriKey(b)) {
@@ -135,7 +147,7 @@ var isItemKeyEqualNormalized = (a, b) => {
   }
 };
 var isItemKeyEqual = (a, b) => {
-  logger2.trace("isKeyEqual", { a, b });
+  logger3.trace("isKeyEqual", { a, b });
   if (isComKey(a) && isComKey(b)) {
     return isComKeyEqual(a, b);
   } else if (isPriKey(a) && isPriKey(b)) {
@@ -149,15 +161,15 @@ var isItemKeyEqual = (a, b) => {
   }
 };
 var isPriKeyEqual = (a, b) => {
-  logger2.trace("isPriKeyEqual", { a, b });
+  logger3.trace("isPriKeyEqual", { a, b });
   return a && b && a.pk === b.pk && a.kt === b.kt;
 };
 var isLocKeyEqual = (a, b) => {
-  logger2.trace("isLocKeyEqual", { a, b });
+  logger3.trace("isLocKeyEqual", { a, b });
   return a && b && a.lk === b.lk && a.kt === b.kt;
 };
 var isComKeyEqual = (a, b) => {
-  logger2.trace("isComKeyEqual", { a, b });
+  logger3.trace("isComKeyEqual", { a, b });
   if (a && b && isPriKeyEqual({ kt: a.kt, pk: a.pk }, { kt: b.kt, pk: b.pk })) {
     if (a.loc.length === b.loc.length) {
       for (let i = 0; i < a.loc.length; i++) {
@@ -174,23 +186,23 @@ var isComKeyEqual = (a, b) => {
   }
 };
 var isItemKey = (key) => {
-  logger2.trace("isItemKey", { key });
+  logger3.trace("isItemKey", { key });
   return key !== void 0 && (isComKey(key) || isPriKey(key));
 };
 var isComKey = (key) => {
-  logger2.trace("isComKey", { key });
-  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && (key.loc !== void 0 && key.loc.length > 0);
+  logger3.trace("isComKey", { key });
+  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && (key.loc !== void 0 && Array.isArray(key.loc));
 };
 var isPriKey = (key) => {
-  logger2.trace("isPriKey", { key });
-  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && (key.loc === void 0 || key.loc.length === 0);
+  logger3.trace("isPriKey", { key });
+  return key !== void 0 && (key.pk !== void 0 && key.kt !== void 0) && key.loc === void 0;
 };
 var isLocKey = (key) => {
-  logger2.trace("isLocKey", { key });
+  logger3.trace("isLocKey", { key });
   return key !== void 0 && (key.lk !== void 0 && key.kt !== void 0);
 };
 var generateKeyArray = (key) => {
-  logger2.trace("generateKeyArray", { key });
+  logger3.trace("generateKeyArray", { key });
   const keys = [];
   if (isComKey(key) || isPriKey(key)) {
     if (isComKey(key)) {
@@ -211,7 +223,7 @@ var generateKeyArray = (key) => {
   return keys;
 };
 var constructPriKey = (pk, kt) => {
-  logger2.trace("constructPriKey", { pk, kt });
+  logger3.trace("constructPriKey", { pk, kt });
   let pri;
   if (typeof pk === "string" || typeof pk === "number") {
     pri = { kt, pk };
@@ -222,7 +234,7 @@ var constructPriKey = (pk, kt) => {
 };
 var cPK = constructPriKey;
 var toKeyTypeArray = (ik) => {
-  logger2.trace("toKeyTypeArray", { ik });
+  logger3.trace("toKeyTypeArray", { ik });
   if (isComKey(ik)) {
     const ck = ik;
     return [ck.kt, ...ck.loc.map((l) => l.kt)];
@@ -231,7 +243,7 @@ var toKeyTypeArray = (ik) => {
   }
 };
 var extractKeyTypeArray = (key) => {
-  logger2.trace("extractKeyTypeArray", { key });
+  logger3.trace("extractKeyTypeArray", { key });
   if (isComKey(key)) {
     const ck = key;
     return [ck.kt, ...ck.loc.map((l) => l.kt)];
@@ -240,12 +252,12 @@ var extractKeyTypeArray = (key) => {
   } else if (Array.isArray(key)) {
     return key.map((locKey) => locKey.kt);
   } else {
-    logger2.warning("extractKeyTypeArray: Unknown key type", { key });
+    logger3.warning("extractKeyTypeArray: Unknown key type", { key });
     return [];
   }
 };
 var abbrevIK = (ik) => {
-  logger2.trace("abbrevIK", { ik });
+  logger3.trace("abbrevIK", { ik });
   if (ik) {
     if (isComKey(ik)) {
       const ck = ik;
@@ -258,7 +270,7 @@ var abbrevIK = (ik) => {
   }
 };
 var abbrevLKA = (keyArray) => {
-  logger2.trace("abbrevLKA", { keyArray });
+  logger3.trace("abbrevLKA", { keyArray });
   if (keyArray === void 0 || keyArray === null) {
     return "null LKA";
   } else {
@@ -272,7 +284,7 @@ var abbrevLKA = (keyArray) => {
   }
 };
 var primaryType = (ik) => {
-  logger2.trace("primaryType", { ik });
+  logger3.trace("primaryType", { ik });
   if (isComKey(ik)) {
     return ik.kt;
   } else {
@@ -280,7 +292,7 @@ var primaryType = (ik) => {
   }
 };
 var itemKeyToLocKeyArray = (ik) => {
-  logger2.trace("itemKeyToLocKeyArray", { ik: abbrevIK(ik) });
+  logger3.trace("itemKeyToLocKeyArray", { ik: abbrevIK(ik) });
   let lka = [];
   if (isComKey(ik)) {
     const ck = ik;
@@ -289,12 +301,12 @@ var itemKeyToLocKeyArray = (ik) => {
     const pk = ik;
     lka = [{ kt: pk.kt, lk: pk.pk }];
   }
-  logger2.trace("itemKeyToLocKeyArray Results", { ik: abbrevIK(ik), lka: abbrevLKA(lka) });
+  logger3.trace("itemKeyToLocKeyArray Results", { ik: abbrevIK(ik), lka: abbrevLKA(lka) });
   return lka;
 };
 var ikToLKA = itemKeyToLocKeyArray;
 var locKeyArrayToItemKey = (lka) => {
-  logger2.trace("locKeyArrayToItemKey", { lka: abbrevLKA(lka) });
+  logger3.trace("locKeyArrayToItemKey", { lka: abbrevLKA(lka) });
   if (lka && lka.length === 1) {
     const priKey = cPK(lka[0].lk, lka[0].kt);
     return priKey;
@@ -538,7 +550,7 @@ var IQFactory = class _IQFactory {
 
 // src/item/IQUtils.ts
 import * as luxon from "luxon";
-var logger3 = logger_default.get("IQUtils");
+var logger4 = logger_default.get("IQUtils");
 var queryToParams = (query) => {
   const params = {};
   if (query.compoundCondition) {
@@ -594,8 +606,8 @@ var paramsToQuery = (params) => {
   return query;
 };
 var isRefQueryMatch = (refKey, queryRef, references) => {
-  logger3.trace("doesRefMatch", { queryRef, references });
-  logger3.debug("Comparing Ref", { refKey, itemRef: references[refKey], queryRef });
+  logger4.trace("doesRefMatch", { queryRef, references });
+  logger4.debug("Comparing Ref", { refKey, itemRef: references[refKey], queryRef });
   if (!references[refKey]) {
     return false;
   }
@@ -614,12 +626,12 @@ var isCompoundConditionQueryMatch = (queryCondition, item) => {
 };
 var isConditionQueryMatch = (queryCondition, item) => {
   const propKey = queryCondition.column;
-  logger3.trace("doesConditionMatch", { propKey, queryCondition, item });
+  logger4.trace("doesConditionMatch", { propKey, queryCondition, item });
   if (item[propKey] === void 0) {
-    logger3.debug("Item does not contain prop under key", { propKey, item });
+    logger4.debug("Item does not contain prop under key", { propKey, item });
     return false;
   }
-  logger3.debug("Comparing Condition", { propKey, itemProp: item[propKey], queryCondition });
+  logger4.debug("Comparing Condition", { propKey, itemProp: item[propKey], queryCondition });
   if (queryCondition.value === null) {
     if (queryCondition.operator === "==") {
       return item[propKey] === null;
@@ -668,7 +680,7 @@ var isConditionQueryMatch = (queryCondition, item) => {
 };
 var isAggQueryMatch = (aggKey, aggQuery, agg) => {
   const aggItem = agg.item;
-  logger3.debug("Comparing Agg", { aggKey, aggItem, aggQuery });
+  logger4.debug("Comparing Agg", { aggKey, aggItem, aggQuery });
   if (!aggItem) {
     return false;
   }
@@ -676,35 +688,35 @@ var isAggQueryMatch = (aggKey, aggQuery, agg) => {
 };
 var isEventQueryMatch = (eventKey, eventQuery, item) => {
   if (!item.events[eventKey]) {
-    logger3.debug("Item does not contain event under key", { eventKey, events: item.events });
+    logger4.debug("Item does not contain event under key", { eventKey, events: item.events });
     return false;
   } else {
     const itemEvent = item.events[eventKey];
     if (itemEvent.at !== null) {
       if (eventQuery.start && !(eventQuery.start.getTime() <= itemEvent.at.getTime())) {
-        logger3.debug("Item date before event start query", { eventQuery, itemEvent });
+        logger4.debug("Item date before event start query", { eventQuery, itemEvent });
         return false;
       }
       if (eventQuery.end && !(eventQuery.end.getTime() > itemEvent.at.getTime())) {
-        logger3.debug("Item date after event end query", { eventQuery, itemEvent });
+        logger4.debug("Item date after event end query", { eventQuery, itemEvent });
         return false;
       }
     } else {
-      logger3.debug("Item event does contains a null at", { itemEvent });
+      logger4.debug("Item event does contains a null at", { itemEvent });
       return false;
     }
     return true;
   }
 };
 var isQueryMatch = (item, query) => {
-  logger3.trace("isMatch", { item, query });
+  logger4.trace("isMatch", { item, query });
   if (query.refs && item.refs) {
     for (const key in query.refs) {
       const queryRef = query.refs[key];
       if (!isRefQueryMatch(key, queryRef.key, item.refs)) return false;
     }
   } else if (query.refs && !item.refs) {
-    logger3.debug("Query contains refs but item does not have refs", { query, item });
+    logger4.debug("Query contains refs but item does not have refs", { query, item });
     return false;
   }
   if (query.compoundCondition && item) {
@@ -734,7 +746,7 @@ var isQueryMatch = (item, query) => {
       }
     }
   } else if (query.aggs && !item.aggs) {
-    logger3.debug("Query contains aggs but item does not have aggs", { query, item });
+    logger4.debug("Query contains aggs but item does not have aggs", { query, item });
     return false;
   }
   return true;
@@ -796,33 +808,33 @@ var abbrevCondition = (condition) => {
   }
 };
 
-// src/item/IUtils.ts
-var logger4 = logger_default.get("IUtils");
+// src/validation/ItemValidator.ts
+var logger5 = logger_default.get("validation", "ItemValidator");
 var validatePKForItem = (item, pkType) => {
   if (!item) {
-    logger4.error("Validating PK, Item is undefined", { item });
+    logger5.error("Validating PK, Item is undefined", { item });
     throw new Error("Validating PK, Item is undefined");
   }
   if (!item.key) {
-    logger4.error("Validating PK, Item does not have a key", { item });
+    logger5.error("Validating PK, Item does not have a key", { item });
     throw new Error("Validating PK, Item does not have a key");
   }
   const keyTypeArray = toKeyTypeArray(item.key);
   if (keyTypeArray[0] !== pkType) {
-    logger4.error("Key Type Array Mismatch", { keyTypeArray, pkType });
+    logger5.error("Key Type Array Mismatch", { keyTypeArray, pkType });
     throw new Error(`Item does not have the correct primary key type. Expected ${pkType}, got ${keyTypeArray[0]}`);
   }
   return item;
 };
 var validatePK = (input, pkType) => {
-  logger4.trace("Checking Return Type", { input });
+  logger5.trace("Checking Return Type", { input });
   if (Array.isArray(input)) {
     return input.map((item) => validatePKForItem(item, pkType));
   }
   return validatePKForItem(input, pkType);
 };
 var validateKeys = (item, keyTypes) => {
-  logger4.trace("Checking Return Type", { item });
+  logger5.trace("Checking Return Type", { item });
   if (!item) {
     throw new Error("validating keys, item is undefined");
   }
@@ -835,22 +847,1244 @@ var validateKeys = (item, keyTypes) => {
   }
   const match = JSON.stringify(keyTypeArray) === JSON.stringify(keyTypes);
   if (!match) {
-    logger4.error("Key Type Array Mismatch", { keyTypeArray, thisKeyTypes: keyTypes });
+    logger5.error("Key Type Array Mismatch", { keyTypeArray, thisKeyTypes: keyTypes });
     throw new Error(`Item does not have the correct key types. Expected [${keyTypes.join(", ")}], but got [${keyTypeArray.join(", ")}]`);
   }
   return item;
 };
+
+// src/item/IUtils.ts
 var isPriItem = (item) => {
   return !!(item && item.key && isPriKey(item.key));
 };
 var isComItem = (item) => {
   return !!(item && item.key && isComKey(item.key));
 };
+
+// src/validation/LocationValidator.ts
+var logger6 = logger_default.get("validation", "LocationValidator");
+var validateLocations = (locations, coordinate, operation) => {
+  if (!locations || locations.length === 0) {
+    return;
+  }
+  const keyTypeArray = coordinate.kta;
+  const expectedLocationTypes = keyTypeArray.slice(1);
+  const actualLocationTypes = locations.map((loc) => loc.kt);
+  logger6.debug(`Validating locations for ${operation}`, {
+    expected: expectedLocationTypes,
+    actual: actualLocationTypes,
+    coordinate: keyTypeArray
+  });
+  if (actualLocationTypes.length > expectedLocationTypes.length) {
+    logger6.error("Location key array has too many elements", {
+      expected: expectedLocationTypes.length,
+      actual: actualLocationTypes.length,
+      expectedTypes: expectedLocationTypes,
+      actualTypes: actualLocationTypes,
+      coordinate,
+      operation
+    });
+    throw new Error(
+      `Invalid location key array for ${operation}: Expected at most ${expectedLocationTypes.length} location keys (hierarchy: [${expectedLocationTypes.join(", ")}]), but received ${actualLocationTypes.length} (types: [${actualLocationTypes.join(", ")}])`
+    );
+  }
+  for (let i = 0; i < actualLocationTypes.length; i++) {
+    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
+      logger6.error("Location key array order mismatch", {
+        position: i,
+        expected: expectedLocationTypes[i],
+        actual: actualLocationTypes[i],
+        expectedHierarchy: expectedLocationTypes,
+        actualOrder: actualLocationTypes,
+        coordinate,
+        operation
+      });
+      throw new Error(
+        `Invalid location key array order for ${operation}: At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}". Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(", ")}]. Received order: [${actualLocationTypes.join(", ")}]`
+      );
+    }
+  }
+  logger6.debug(`Location key array validation passed for ${operation}`, { locations });
+};
+var isValidLocations = (locations, coordinate, operation) => {
+  try {
+    validateLocations(locations, coordinate, operation);
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+
+// src/validation/KeyValidator.ts
+var logger7 = logger_default.get("validation", "KeyValidator");
+var validateLocationKeyOrder = (key, coordinate, operation) => {
+  const keyTypeArray = coordinate.kta;
+  const expectedLocationTypes = keyTypeArray.slice(1);
+  const actualLocationTypes = key.loc.map((loc) => loc.kt);
+  if (expectedLocationTypes.length !== actualLocationTypes.length) {
+    logger7.error("Location key array length mismatch", {
+      expected: expectedLocationTypes.length,
+      actual: actualLocationTypes.length,
+      key,
+      coordinate,
+      operation
+    });
+    const expectedOrder = expectedLocationTypes.map(
+      (kt, i) => `  [${i}] { kt: '${kt}', lk: <value> }`
+    ).join("\n");
+    const actualOrder = key.loc.map(
+      (loc, i) => `  [${i}] { kt: '${loc.kt}', lk: ${JSON.stringify(loc.lk)} }`
+    ).join("\n");
+    throw new Error(
+      `Location key array length mismatch for ${operation} operation.
+
+Expected ${expectedLocationTypes.length} location keys but received ${actualLocationTypes.length}.
+
+Expected location key order for '${keyTypeArray[0]}':
+${expectedOrder}
+
+Received location key order:
+${actualOrder}`
+    );
+  }
+  for (let i = 0; i < expectedLocationTypes.length; i++) {
+    if (expectedLocationTypes[i] !== actualLocationTypes[i]) {
+      logger7.error("Location key array order mismatch", {
+        position: i,
+        expected: expectedLocationTypes[i],
+        actual: actualLocationTypes[i],
+        key,
+        coordinate,
+        operation
+      });
+      const expectedOrder = expectedLocationTypes.map(
+        (kt, i2) => `  [${i2}] { kt: '${kt}', lk: <value> }`
+      ).join("\n");
+      const actualOrder = key.loc.map(
+        (loc, i2) => `  [${i2}] { kt: '${loc.kt}', lk: ${JSON.stringify(loc.lk)} }`
+      ).join("\n");
+      throw new Error(
+        `Location key array order mismatch for ${operation} operation.
+
+At position ${i}, expected key type "${expectedLocationTypes[i]}" but received "${actualLocationTypes[i]}".
+
+Expected location key order for '${keyTypeArray[0]}':
+${expectedOrder}
+
+Received location key order:
+${actualOrder}
+
+Tip: Location keys must be ordered according to the hierarchy: [${expectedLocationTypes.join(", ")}]`
+      );
+    }
+  }
+};
+var validateKey = (key, coordinate, operation) => {
+  logger7.debug(`Validating key for ${operation}`, { key, coordinate: coordinate.kta });
+  if (!key || key === null) {
+    throw new Error(
+      `Invalid key structure for ${operation} operation.
+
+The provided key is null or undefined.
+
+Valid key formats:
+  PriKey: { kt: string, pk: string|number }
+  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
+    );
+  }
+  const isCompositeLibrary = coordinate.kta.length > 1;
+  const keyIsComposite = isComKey(key);
+  const keyIsPrimary = isPriKey(key);
+  if (isCompositeLibrary && !keyIsComposite) {
+    logger7.error(`Composite library received primary key in ${operation}`, { key, coordinate });
+    const keyTypeArray = coordinate.kta;
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+This is a composite item library. You must provide a ComKey with location keys.
+
+Expected: ComKey with format:
+  {
+    kt: '${keyTypeArray[0]}',
+    pk: string|number,
+    loc: [
+` + keyTypeArray.slice(1).map((kt) => `      { kt: '${kt}', lk: string|number }`).join(",\n") + `
+    ]
+  }
+
+Received: PriKey with format:
+  ${JSON.stringify(key, null, 2)}
+
+Example correct usage:
+  library.operations.${operation}({
+    kt: '${keyTypeArray[0]}',
+    pk: 'item-id',
+    loc: [${keyTypeArray.slice(1).map((kt) => `{ kt: '${kt}', lk: 'parent-id' }`).join(", ")}]
+  })`
+    );
+  }
+  if (!isCompositeLibrary && keyIsComposite) {
+    logger7.error(`Primary library received composite key in ${operation}`, { key, coordinate });
+    const keyTypeArray = coordinate.kta;
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+This is a primary item library. You should provide a PriKey without location keys.
+
+Expected: PriKey with format:
+  { kt: '${keyTypeArray[0]}', pk: string|number }
+
+Received: ComKey with format:
+  ${JSON.stringify(key, null, 2)}
+
+Example correct usage:
+  library.operations.${operation}({ kt: '${keyTypeArray[0]}', pk: 'item-id' })`
+    );
+  }
+  if (!keyIsPrimary && !keyIsComposite) {
+    logger7.error(`Invalid key structure in ${operation}`, { key, coordinate });
+    throw new Error(
+      `Invalid key structure for ${operation} operation.
+
+The provided key does not match PriKey or ComKey format.
+
+Received:
+  ${JSON.stringify(key, null, 2)}
+
+Valid key formats:
+  PriKey: { kt: string, pk: string|number }
+  ComKey: { kt: string, pk: string|number, loc: Array<{ kt: string, lk: string|number }> }`
+    );
+  }
+  const expectedKeyType = coordinate.kta[0];
+  if (key.kt !== expectedKeyType) {
+    logger7.error(`Key type mismatch in ${operation}`, {
+      expected: expectedKeyType,
+      received: key.kt,
+      key,
+      coordinate
+    });
+    throw new Error(
+      `Invalid key type for ${operation} operation.
+
+Expected key type: '${expectedKeyType}'
+Received key type: '${key.kt}'
+
+Example correct usage:
+  library.operations.${operation}({ kt: '${expectedKeyType}', pk: 'item-id', ... })`
+    );
+  }
+  if (keyIsComposite) {
+    const comKey = key;
+    if (comKey.loc.length === 0) {
+      logger7.debug(`Empty loc array detected in ${operation} - will search across all locations`, { key });
+    } else {
+      validateLocationKeyOrder(comKey, coordinate, operation);
+    }
+  }
+  logger7.debug(`Key validation passed for ${operation}`, { key });
+};
+var validatePriKey = (key, expectedType, operation) => {
+  if (!key || key === null) {
+    throw new Error(`[${operation}] PriKey is undefined or null`);
+  }
+  if (!key.kt) {
+    throw new Error(`[${operation}] PriKey is missing 'kt' field`);
+  }
+  if (key.kt !== expectedType) {
+    throw new Error(
+      `[${operation}] PriKey has incorrect type.
+Expected: '${expectedType}'
+Received: '${key.kt}'`
+    );
+  }
+  if (typeof key.pk === "undefined" || key.pk === null) {
+    throw new Error(`[${operation}] PriKey is missing 'pk' field`);
+  }
+};
+var validateComKey = (key, coordinate, operation) => {
+  if (!key || key === null) {
+    throw new Error(`[${operation}] ComKey is undefined or null`);
+  }
+  if (!key.kt) {
+    throw new Error(`[${operation}] ComKey is missing 'kt' field`);
+  }
+  if (key.kt !== coordinate.kta[0]) {
+    throw new Error(
+      `[${operation}] ComKey has incorrect type.
+Expected: '${coordinate.kta[0]}'
+Received: '${key.kt}'`
+    );
+  }
+  if (typeof key.pk === "undefined" || key.pk === null) {
+    throw new Error(`[${operation}] ComKey is missing 'pk' field`);
+  }
+  if (!Array.isArray(key.loc)) {
+    throw new Error(`[${operation}] ComKey is missing or invalid 'loc' field (must be an array)`);
+  }
+  if (key.loc.length > 0) {
+    validateLocationKeyOrder(key, coordinate, operation);
+  }
+};
+
+// src/validation/QueryValidator.ts
+var logger8 = logger_default.get("validation", "QueryValidator");
+var validateQuery = (query, operation) => {
+  if (typeof query === "undefined" || query === null) {
+    return;
+  }
+  if (typeof query !== "object") {
+    logger8.error(`Invalid query type for ${operation}`, { query, type: typeof query });
+    throw new Error(
+      `[${operation}] Invalid query parameter.
+
+Expected: object or undefined
+Received: ${typeof query}
+
+Example valid queries:
+  {}
+  { filter: { status: 'active' } }
+  { limit: 10, sort: { field: 'name', order: 'asc' } }`
+    );
+  }
+  if (Array.isArray(query)) {
+    logger8.error(`Query cannot be an array for ${operation}`, { query });
+    throw new Error(
+      `[${operation}] Invalid query parameter.
+
+Query cannot be an array.
+Received: ${JSON.stringify(query)}`
+    );
+  }
+  logger8.debug(`Query validation passed for ${operation}`, { query });
+};
+var validateOperationParams = (params, operation) => {
+  if (typeof params === "undefined") {
+    return;
+  }
+  if (params === null) {
+    logger8.error(`Params cannot be null for ${operation}`, { params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Parameters cannot be null.
+Expected: object or undefined
+Received: null
+
+Example valid parameters:
+  {}
+  { email: 'user@example.com' }
+  { status: 'active', limit: 10 }`
+    );
+  }
+  if (typeof params !== "object") {
+    logger8.error(`Invalid params type for ${operation}`, { params, type: typeof params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Expected: object or undefined
+Received: ${typeof params}
+
+Example valid parameters:
+  {}
+  { email: 'user@example.com' }
+  { status: 'active', limit: 10 }`
+    );
+  }
+  if (Array.isArray(params)) {
+    logger8.error(`Params cannot be an array for ${operation}`, { params });
+    throw new Error(
+      `[${operation}] Invalid operation parameters.
+
+Parameters cannot be an array.
+Received: ${JSON.stringify(params)}`
+    );
+  }
+  for (const [key, value] of Object.entries(params)) {
+    const valueType = typeof value;
+    const isValidType = valueType === "string" || valueType === "number" || valueType === "boolean" || value instanceof Date || Array.isArray(value) && value.every(
+      (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v instanceof Date
+    );
+    if (!isValidType) {
+      logger8.error(`Invalid param value type for ${operation}`, { key, value, valueType });
+      throw new Error(
+        `[${operation}] Invalid value type for parameter "${key}".
+
+Allowed types: string, number, boolean, Date, or arrays of these types
+Received: ${valueType}
+Value: ${JSON.stringify(value)}`
+      );
+    }
+  }
+  logger8.debug(`Operation params validation passed for ${operation}`, { params });
+};
+var validateFinderName = (finder, operation) => {
+  if (!finder || typeof finder !== "string") {
+    logger8.error(`Invalid finder name for ${operation}`, { finder, type: typeof finder });
+    throw new Error(
+      `[${operation}] Finder name must be a non-empty string.
+
+Received: ${JSON.stringify(finder)}`
+    );
+  }
+  if (finder.trim().length === 0) {
+    logger8.error(`Empty finder name for ${operation}`, { finder });
+    throw new Error(
+      `[${operation}] Finder name cannot be empty or whitespace only.
+
+Received: "${finder}"`
+    );
+  }
+  logger8.debug(`Finder name validation passed for ${operation}`, { finder });
+};
+var validateActionName = (action, operation) => {
+  if (!action || typeof action !== "string") {
+    logger8.error(`Invalid action name for ${operation}`, { action, type: typeof action });
+    throw new Error(
+      `[${operation}] Action name must be a non-empty string.
+
+Received: ${JSON.stringify(action)}`
+    );
+  }
+  if (action.trim().length === 0) {
+    logger8.error(`Empty action name for ${operation}`, { action });
+    throw new Error(
+      `[${operation}] Action name cannot be empty or whitespace only.
+
+Received: "${action}"`
+    );
+  }
+  logger8.debug(`Action name validation passed for ${operation}`, { action });
+};
+var validateFacetName = (facet, operation) => {
+  if (!facet || typeof facet !== "string") {
+    logger8.error(`Invalid facet name for ${operation}`, { facet, type: typeof facet });
+    throw new Error(
+      `[${operation}] Facet name must be a non-empty string.
+
+Received: ${JSON.stringify(facet)}`
+    );
+  }
+  if (facet.trim().length === 0) {
+    logger8.error(`Empty facet name for ${operation}`, { facet });
+    throw new Error(
+      `[${operation}] Facet name cannot be empty or whitespace only.
+
+Received: "${facet}"`
+    );
+  }
+  logger8.debug(`Facet name validation passed for ${operation}`, { facet });
+};
+
+// src/errors/ActionError.ts
+var ActionError = class extends Error {
+  constructor(errorInfo, cause) {
+    super(errorInfo.message);
+    this.errorInfo = errorInfo;
+    this.name = "ActionError";
+    this.cause = cause;
+    if (!this.errorInfo.technical) {
+      this.errorInfo.technical = { timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    }
+    if (!this.errorInfo.technical.timestamp) {
+      this.errorInfo.technical.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    }
+  }
+  toJSON() {
+    return this.errorInfo;
+  }
+};
+
+// src/errors/ValidationError.ts
+var ValidationError = class extends ActionError {
+  constructor(message, validOptions, suggestedAction, conflictingValue) {
+    super({
+      code: "VALIDATION_ERROR",
+      message,
+      operation: { type: "create", name: "", params: {} },
+      // Will be filled by wrapper
+      context: { itemType: "" },
+      // Will be filled by wrapper
+      details: {
+        validOptions,
+        suggestedAction,
+        retryable: true,
+        conflictingValue
+      },
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
+// src/errors/NotFoundError.ts
+var NotFoundError = class extends ActionError {
+  constructor(message, itemType, key) {
+    super({
+      code: "NOT_FOUND",
+      message,
+      operation: { type: "get", name: "", params: {} },
+      context: {
+        itemType,
+        key: typeof key === "object" ? key : { primary: key }
+      },
+      details: { retryable: false },
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
+// src/errors/BusinessLogicError.ts
+var BusinessLogicError = class extends ActionError {
+  constructor(message, suggestedAction, retryable = false) {
+    super({
+      code: "BUSINESS_LOGIC_ERROR",
+      message,
+      operation: { type: "action", name: "", params: {} },
+      context: { itemType: "" },
+      details: {
+        suggestedAction,
+        retryable
+      },
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
+// src/errors/PermissionError.ts
+var PermissionError = class extends ActionError {
+  constructor(message, requiredPermission, currentPermissions) {
+    super({
+      code: "PERMISSION_DENIED",
+      message,
+      operation: { type: "action", name: "", params: {} },
+      context: {
+        itemType: "",
+        ...requiredPermission && { requiredPermission }
+      },
+      details: {
+        ...requiredPermission && {
+          suggestedAction: `Required permission: ${requiredPermission}`,
+          expectedValue: requiredPermission
+        },
+        ...currentPermissions && { conflictingValue: currentPermissions },
+        retryable: false
+      },
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
+// src/errors/DuplicateError.ts
+var DuplicateError = class extends ActionError {
+  constructor(message, existingItemIdOrKey, duplicateField) {
+    let existingItemId = null;
+    let keyInfo = null;
+    if (typeof existingItemIdOrKey === "object" && existingItemIdOrKey !== null) {
+      existingItemId = existingItemIdOrKey.pk || existingItemIdOrKey.id || existingItemIdOrKey.primary || null;
+      if (existingItemId !== null) {
+        keyInfo = {
+          primary: existingItemId,
+          ...existingItemIdOrKey
+        };
+      } else {
+        keyInfo = existingItemIdOrKey;
+      }
+    } else if (typeof existingItemIdOrKey !== "undefined") {
+      existingItemId = existingItemIdOrKey;
+      keyInfo = { primary: existingItemId };
+    }
+    super({
+      code: "DUPLICATE_ERROR",
+      message,
+      operation: { type: "create", name: "", params: {} },
+      context: {
+        itemType: "",
+        ...keyInfo && { key: keyInfo },
+        ...existingItemId && {
+          affectedItems: [{
+            id: existingItemId,
+            type: "",
+            displayName: `Existing item with ${duplicateField || "key"}`
+          }]
+        }
+      },
+      details: {
+        retryable: false,
+        conflictingValue: duplicateField
+      },
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    });
+  }
+};
+
+// src/operations/errorEnhancer.ts
+async function executeWithContext(operation, context) {
+  try {
+    return await operation();
+  } catch (error) {
+    throw enhanceError(error, context);
+  }
+}
+function executeWithContextSync(operation, context) {
+  try {
+    return operation();
+  } catch (error) {
+    throw enhanceError(error, context);
+  }
+}
+function enhanceError(error, context) {
+  if (!(error instanceof ActionError)) {
+    return error;
+  }
+  error.errorInfo.operation = {
+    type: context.operationType,
+    name: context.operationName,
+    params: context.params
+  };
+  if (!error.errorInfo.context.itemType) {
+    error.errorInfo.context.itemType = context.itemType;
+  }
+  if (context.key) {
+    const existingKey = error.errorInfo.context.key;
+    const hasNoPrimaryKey = !existingKey || typeof existingKey.primary === "undefined";
+    const hasNoCompositeKey = !existingKey || !existingKey.composite;
+    const shouldOverride = hasNoPrimaryKey && hasNoCompositeKey;
+    if (shouldOverride) {
+      error.errorInfo.context.key = extractKeyInfo(context.key);
+    }
+  }
+  if (context.locations && context.locations.length > 0 && !error.errorInfo.context.parentLocation) {
+    error.errorInfo.context.parentLocation = {
+      id: context.locations[0].lk,
+      type: context.locations[0].kt
+    };
+  }
+  return error;
+}
+function extractKeyInfo(key) {
+  if ("loc" in key) {
+    const ktaArray = Array.isArray(key.kt) ? key.kt : [key.kt];
+    const locations = Array.isArray(key.loc) ? key.loc : [];
+    return {
+      composite: {
+        sk: key.pk,
+        kta: ktaArray,
+        locations: locations.map((loc) => ({
+          lk: loc.lk,
+          kt: loc.kt
+        }))
+      }
+    };
+  } else if ("pk" in key) {
+    return { primary: key.pk };
+  }
+  return { primary: JSON.stringify(key) };
+}
+function isActionError(error) {
+  return error instanceof ActionError;
+}
+function getErrorInfo(error) {
+  if (isActionError(error)) {
+    return error.toJSON();
+  }
+  if (error instanceof Error) {
+    return {
+      code: "UNKNOWN_ERROR",
+      message: error.message,
+      technical: {
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        stackTrace: error.stack
+      }
+    };
+  }
+  return {
+    code: "UNKNOWN_ERROR",
+    message: String(error),
+    technical: {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
+// src/operations/Operations.ts
+function isPriKey2(key) {
+  return !("loc" in key) || !key.loc;
+}
+function isComKey2(key) {
+  return "loc" in key && key.loc && Array.isArray(key.loc) && key.loc.length > 0;
+}
+
+// src/operations/wrappers/createOneWrapper.ts
+var logger9 = logger_default.get("operations", "wrappers", "one");
+function createOneWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "one";
+  return async (query, locations) => {
+    if (options.debug) {
+      logger9.debug(`[${operationName}] Called with:`, { query, locations });
+    }
+    if (!options.skipValidation) {
+      try {
+        validateQuery(query, operationName);
+        validateLocations(locations, coordinate, operationName);
+      } catch (error) {
+        throw error;
+      }
+    }
+    const normalizedQuery = query ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(normalizedQuery, normalizedLocations);
+      if (options.debug) {
+        logger9.debug(`[${operationName}] Result:`, result ? "found" : "not found");
+      }
+      if (result && !options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [query, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      const enhanced = new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+      if (error.stack) {
+        enhanced.stack = error.stack;
+      }
+      throw enhanced;
+    }
+  };
+}
+
+// src/operations/wrappers/createAllWrapper.ts
+var logger10 = logger_default.get("operations", "wrappers", "all");
+function createAllWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "all";
+  return async (query, locations) => {
+    if (options.debug) {
+      logger10.debug(`[${operationName}] Called with:`, { query, locations });
+    }
+    if (!options.skipValidation) {
+      validateQuery(query, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    const normalizedQuery = query ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(normalizedQuery, normalizedLocations);
+      if (options.debug) {
+        logger10.debug(`[${operationName}] Result: ${result.length} items`);
+      }
+      if (!options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [query, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createGetWrapper.ts
+var logger11 = logger_default.get("operations", "wrappers", "get");
+function createGetWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "get";
+  return async (key) => {
+    if (options.debug) {
+      logger11.debug(`[${operationName}] Called with key:`, key);
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+    }
+    try {
+      const result = await implementation(key);
+      if (options.debug) {
+        logger11.debug(`[${operationName}] Result:`, result ? "found" : "not found");
+      }
+      if (result && !options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createCreateWrapper.ts
+var logger12 = logger_default.get("operations", "wrappers", "create");
+function createCreateWrapper(coordinate, implementation, wrapperOptions = {}) {
+  const operationName = wrapperOptions.operationName || "create";
+  return async (item, createOptions) => {
+    if (wrapperOptions.debug) {
+      logger12.debug(`[${operationName}] Called with:`, { item, options: createOptions });
+    }
+    if (!wrapperOptions.skipValidation) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) {
+        throw new Error(
+          `[${operationName}] Invalid item parameter.
+
+Expected: object
+Received: ${Array.isArray(item) ? "array" : typeof item}`
+        );
+      }
+      if (createOptions) {
+        if ("key" in createOptions) {
+          validateKey(createOptions.key, coordinate, operationName);
+        }
+        if ("locations" in createOptions) {
+          validateLocations(createOptions.locations, coordinate, operationName);
+        }
+      }
+    }
+    try {
+      const result = await implementation(item, createOptions);
+      if (wrapperOptions.debug) {
+        logger12.debug(`[${operationName}] Created item:`, result.key);
+      }
+      if (!wrapperOptions.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (wrapperOptions.onError) {
+        const context = {
+          operationName,
+          params: [item, createOptions],
+          coordinate
+        };
+        throw wrapperOptions.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createUpdateWrapper.ts
+var logger13 = logger_default.get("operations", "wrappers", "update");
+function createUpdateWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "update";
+  return async (key, item) => {
+    if (options.debug) {
+      logger13.debug(`[${operationName}] Called with:`, { key, item });
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+      if (!item || typeof item !== "object" || Array.isArray(item)) {
+        throw new Error(
+          `[${operationName}] Invalid item parameter.
+
+Expected: object
+Received: ${Array.isArray(item) ? "array" : typeof item}`
+        );
+      }
+    }
+    try {
+      const result = await implementation(key, item);
+      if (options.debug) {
+        logger13.debug(`[${operationName}] Updated item:`, result.key);
+      }
+      if (!options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key, item],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createUpsertWrapper.ts
+var logger14 = logger_default.get("operations", "wrappers", "upsert");
+function createUpsertWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "upsert";
+  return async (key, item, locations) => {
+    if (options.debug) {
+      logger14.debug(`[${operationName}] Called with:`, { key, item, locations });
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+      validateLocations(locations, coordinate, operationName);
+      if (!item || typeof item !== "object" || Array.isArray(item)) {
+        throw new Error(
+          `[${operationName}] Invalid item parameter.
+
+Expected: object
+Received: ${Array.isArray(item) ? "array" : typeof item}`
+        );
+      }
+    }
+    try {
+      const result = await implementation(key, item);
+      if (options.debug) {
+        logger14.debug(`[${operationName}] Upserted item:`, result.key);
+      }
+      if (!options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key, item, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createRemoveWrapper.ts
+var logger15 = logger_default.get("operations", "wrappers", "remove");
+function createRemoveWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "remove";
+  return async (key) => {
+    if (options.debug) {
+      logger15.debug(`[${operationName}] Called with key:`, key);
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+    }
+    try {
+      const result = await implementation(key);
+      if (options.debug) {
+        logger15.debug(`[${operationName}] Removed item:`, key);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createFindWrapper.ts
+var logger16 = logger_default.get("operations", "wrappers", "find");
+function createFindWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "find";
+  return async (finder, params, locations) => {
+    if (options.debug) {
+      logger16.debug(`[${operationName}] Called:`, { finder, params, locations });
+    }
+    if (!options.skipValidation) {
+      validateFinderName(finder, operationName);
+      validateOperationParams(params, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    const normalizedParams = params ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(finder, normalizedParams, normalizedLocations);
+      if (options.debug) {
+        logger16.debug(`[${operationName}] Found ${result.length} items for finder "${finder}"`);
+      }
+      if (!options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [finder, params, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed for finder "${finder}": ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createFindOneWrapper.ts
+var logger17 = logger_default.get("operations", "wrappers", "findOne");
+function createFindOneWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "findOne";
+  return async (finder, params, locations) => {
+    if (options.debug) {
+      logger17.debug(`[${operationName}] Called:`, { finder, params, locations });
+    }
+    if (!options.skipValidation) {
+      validateFinderName(finder, operationName);
+      validateOperationParams(params, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    const normalizedParams = params ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(finder, normalizedParams, normalizedLocations);
+      if (options.debug) {
+        logger17.debug(`[${operationName}] Result for finder "${finder}":`, result ? "found" : "not found");
+      }
+      if (result && !options.skipValidation) {
+        return validatePK(result, coordinate.kta[0]);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [finder, params, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Operation failed for finder "${finder}": ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createActionWrapper.ts
+var logger18 = logger_default.get("operations", "wrappers", "action");
+function createActionWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "action";
+  return async (key, action, params) => {
+    if (options.debug) {
+      logger18.debug(`[${operationName}] Called:`, { key, action, params });
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+      validateActionName(action, operationName);
+      validateOperationParams(params, operationName);
+    }
+    const normalizedParams = params ?? {};
+    try {
+      const result = await implementation(key, action, normalizedParams);
+      if (options.debug) {
+        logger18.debug(`[${operationName}] Action "${action}" completed:`, {
+          itemKey: result[0].key,
+          affectedKeys: result[1].length
+        });
+      }
+      if (!options.skipValidation) {
+        const validatedItem = validatePK(result[0], coordinate.kta[0]);
+        return [validatedItem, result[1]];
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key, action, params],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Action "${action}" failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createAllActionWrapper.ts
+var logger19 = logger_default.get("operations", "wrappers", "allAction");
+function createAllActionWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "allAction";
+  return async (action, params, locations) => {
+    if (options.debug) {
+      logger19.debug(`[${operationName}] Called:`, { action, params, locations });
+    }
+    if (!options.skipValidation) {
+      validateActionName(action, operationName);
+      validateOperationParams(params, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    const normalizedParams = params ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(action, normalizedParams, normalizedLocations);
+      if (options.debug) {
+        logger19.debug(`[${operationName}] Action "${action}" completed:`, {
+          itemsAffected: result[0].length,
+          affectedKeys: result[1].length
+        });
+      }
+      if (!options.skipValidation) {
+        const validatedItems = validatePK(result[0], coordinate.kta[0]);
+        return [validatedItems, result[1]];
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [action, params, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Action "${action}" failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createFacetWrapper.ts
+var logger20 = logger_default.get("operations", "wrappers", "facet");
+function createFacetWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "facet";
+  return async (key, facet, params) => {
+    if (options.debug) {
+      logger20.debug(`[${operationName}] Called:`, { key, facet, params });
+    }
+    if (!options.skipValidation) {
+      validateKey(key, coordinate, operationName);
+      validateFacetName(facet, operationName);
+      validateOperationParams(params, operationName);
+    }
+    const normalizedParams = params ?? {};
+    try {
+      const result = await implementation(key, facet, normalizedParams);
+      if (options.debug) {
+        logger20.debug(`[${operationName}] Facet "${facet}" completed`);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [key, facet, params],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Facet "${facet}" failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
+
+// src/operations/wrappers/createAllFacetWrapper.ts
+var logger21 = logger_default.get("operations", "wrappers", "allFacet");
+function createAllFacetWrapper(coordinate, implementation, options = {}) {
+  const operationName = options.operationName || "allFacet";
+  return async (facet, params, locations) => {
+    if (options.debug) {
+      logger21.debug(`[${operationName}] Called:`, { facet, params, locations });
+    }
+    if (!options.skipValidation) {
+      validateFacetName(facet, operationName);
+      validateOperationParams(params, operationName);
+      validateLocations(locations, coordinate, operationName);
+    }
+    const normalizedParams = params ?? {};
+    const normalizedLocations = locations ?? [];
+    try {
+      const result = await implementation(facet, normalizedParams, normalizedLocations);
+      if (options.debug) {
+        logger21.debug(`[${operationName}] Facet "${facet}" completed`);
+      }
+      return result;
+    } catch (error) {
+      if (options.onError) {
+        const context = {
+          operationName,
+          params: [facet, params, locations],
+          coordinate
+        };
+        throw options.onError(error, context);
+      }
+      throw new Error(
+        `[${operationName}] Facet "${facet}" failed: ${error.message}`,
+        { cause: error }
+      );
+    }
+  };
+}
 export {
   AItemService,
+  ActionError,
+  BusinessLogicError,
   Dictionary,
+  DuplicateError,
   IFactory,
   IQFactory,
+  NotFoundError,
+  PermissionError,
+  ValidationError,
   abbrevAgg,
   abbrevCompoundCondition,
   abbrevCondition,
@@ -860,10 +2094,29 @@ export {
   abbrevRef,
   cPK,
   constructPriKey,
+  createActionWrapper,
+  createAllActionWrapper,
+  createAllFacetWrapper,
+  createAllWrapper,
+  createCoordinate,
+  createCreateWrapper,
+  createFacetWrapper,
+  createFindOneWrapper,
+  createFindWrapper,
+  createGetWrapper,
   createNormalizedHashFunction,
+  createOneWrapper,
+  createRemoveWrapper,
+  createUpdateWrapper,
+  createUpsertWrapper,
+  enhanceError,
+  executeWithContext,
+  executeWithContextSync,
   extractKeyTypeArray,
   generateKeyArray,
+  getErrorInfo,
   ikToLKA,
+  isActionError,
   isComItem,
   isComKey,
   isComKeyEqual,
@@ -875,6 +2128,8 @@ export {
   isLocKey,
   isLocKeyEqual,
   isLocKeyEqualNormalized,
+  isComKey2 as isOperationComKey,
+  isPriKey2 as isOperationPriKey,
   isPriItem,
   isPriKey,
   isPriKeyEqual,
@@ -884,6 +2139,7 @@ export {
   isValidItemKey,
   isValidLocKey,
   isValidLocKeyArray,
+  isValidLocations,
   isValidPriKey,
   itemKeyToLocKeyArray,
   lkaToIK,
@@ -892,6 +2148,15 @@ export {
   primaryType,
   queryToParams,
   toKeyTypeArray,
+  validateActionName,
+  validateComKey,
+  validateFacetName,
+  validateFinderName,
+  validateKey,
   validateKeys,
-  validatePK
+  validateLocations,
+  validateOperationParams,
+  validatePK,
+  validatePriKey,
+  validateQuery
 };