@litusarchieve18/agricore-utils 1.0.26 → 1.0.28

package/README.md

@@ -183,6 +183,12 @@ Run the publish command:
 Bash
 npm publish --access public
 📝 Version History
+V1.0.29 — 
+
+V1.0.28 — altered the logic and added scope aware filtering and write-time validation in priceHelpers.ts
+
+V1.0.27 — adding get price helper, and adding adapter pattern to handle the conflicting price
+
 V1.0.26 — updating evaluatebaseAccess to try look up the parent scope given the current scope is not 
 
 V1.0.25 — adding privileges and changing RESOURCE_PATHS

package/dist/{chunk-GZRAFNPA.mjs → chunk-Y5KVDVNY.mjs}

@@ -64,7 +64,8 @@ var ERROR_DICTIONARY = {
   "400": { title: "Data Conflict", text: "A conflict occurred with an existing record. Please review and try again." },
   "402": { title: "Duplicate Entry", text: "A record with this name or identifier already exists." },
   "403": { title: "Edit Conflict", text: "This record was recently updated by someone else. Please refresh and try again." },
-  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." }
+  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." },
+  "405": { title: "Pricing Conflict", text: "Multiple active prices were found for this product. An administrator must resolve the conflict before this price can be used." }
 };
 var UserRole = {
   OWNER: "owner",

package/dist/{constants-C0zV05Cf.d.mts → constants-CrAPx_xU.d.mts}

@@ -206,6 +206,66 @@ type ProductUnitType = typeof ProductUnit[keyof typeof ProductUnit];
 type CatalogSyncStatusType = typeof CatalogSyncStatus[keyof typeof CatalogSyncStatus];
 type StorageType = typeof StoragePhases[keyof typeof StoragePhases];
 type StockPolicyTierType = typeof StockPolicyTier[keyof typeof StockPolicyTier];
+interface PricingContext {
+    productId: string;
+    companyId: string;
+    facilityId?: string;
+    accountCode?: string | null;
+    contractReferenceNumber?: string | null;
+    evaluationDate?: Date;
+}
+interface PriceResolutionResult {
+    unitPriceCents: number;
+    minimumOrderQuantity: number;
+    leadTimeDays: number | null;
+    priceSource: 'EXPLICIT_CONTRACT' | 'ACCOUNT_MATRIX' | 'INTERNAL_DEFAULT' | 'PRODUCT_FALLBACK';
+    sourceRecordId: string;
+}
+interface PricingDataSource {
+    findContractPrice(args: {
+        productId: string;
+        contractReferenceNumber: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findAccountPrice(args: {
+        productId: string;
+        accountCode: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findDefaultPrice(args: {
+        productId: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findBaseProduct(args: {
+        productId: string;
+    }): Promise<BaseProductRow | null>;
+}
+interface MatrixRow {
+    canonicalId: string;
+    matrixUnitPriceCents: number;
+    minimumOrderQuantity: number;
+    leadTimeDays: number | null;
+}
+interface BaseProductRow {
+    canonicalId: string;
+    unitPriceCents: number;
+}
+type Tier = 'EXPLICIT_CONTRACT' | 'ACCOUNT_MATRIX' | 'INTERNAL_DEFAULT';
+interface PriceConflictCandidate {
+    sourceRecordId: string;
+    unitPriceCents: number;
+    validFrom: string;
+    validTo: string | null;
+}
+interface ShadowedCleanMatch {
+    tier: Tier;
+    unitPriceCents: number;
+    sourceRecordId: string;
+    matchedOn: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    };
+}
 
 declare const MOD: {
     readonly OPERATIONS: "OPR";
@@ -686,4 +746,4 @@ declare const StockPolicyTier: {
     readonly BY_LOCATION: 3;
 };
 
-export { NettingType as $, ACCESS_RANK as A, BarcodeNamespace as B, CAR_SUPPORTED_EVIDENCE_MIME_TYPES as C, type CorrectiveActionCompileTaskMetadata as D, type CorrectiveActionGenerationSource as E, type CorrectiveActionStatus as F, CropCycleStatus as G, DOCUMENT_DISPLAY_INFO as H, DOCUMENT_MENU_MAP as I, DocumentCategory as J, DocumentType as K, ERROR_DICTIONARY as L, EVERYONE as M, EmitterType as N, EnabledModule as O, FORM_REGISTRY as P, FacilityType as Q, type FileUploadTaskType as R, type FormMeta as S, HarvestMethod as T, type InfrastructureFields as U, LinkedStatus as V, MOD as W, MODULE_LABELS as X, MicroclimateZone as Y, MimeType as Z, type ModCode as _, ACT as a, type NormalizedSignatureValue as a0, NotificationMode as a1, OrderStatus as a2, type PermissionLevel as a3, PhysicalState as a4, PlantingMethod as a5, ProductType as a6, type ProductTypeType as a7, ProductUnit as a8, type ProductUnitType as a9, TaskStatus as aA, TaskType as aB, type TaskTypeConfig as aC, type TemplateScopeLevel as aD, TransactionType as aE, TrellisType as aF, UserPrivilege as aG, type UserPrivilegeType as aH, UserRole as aI, type UserRoleAssignment as aJ, type UserRoleType as aK, VigorRating as aL, WaterSource as aM, type WireSession as aN, RESOURCE_MODULE_MAP as aa, RESOURCE_PATHS as ab, RESOURCE_REQUIREMENTS as ac, ROLE_SECTIONS_BY_KEY as ad, RelationshipType as ae, type ResolvedError as af, type ResourceOverrides as ag, type ResourceRequirement as ah, type RoleAssignment as ai, RowOrientation as aj, SENTINEL_UUID as ak, SESSION_SCHEMA as al, SIGNATURE_MODES as am, type SchemaField as an, type ScopeType as ao, type SignatureInput as ap, type SignatureMode as aq, SoilTexture as ar, StockPolicyTier as as, type StockPolicyTierType as at, StoragePhases as au, type StorageType as av, TASK_TYPE_REGISTRY as aw, TEMPLATE_SCOPE_LEVELS as ax, type TabConfig as ay, TargetEntityType as az, AccessLevel as b, type AccessLevelType as c, type AgriCoreSession as d, ApprovalStatus as e, ApprovalType as f, AuditStatus as g, AuditType as h, type AuthScopeFields as i, type AvailableScope as j, type BarcodeNamespaceType as k, BarcodeType as l, type BarcodeTypeType as m, type Base44Id as n, CAR_SUPPORTED_SIGNATURE_MIME_TYPES as o, CAT as p, CATEGORY_TABS as q, CORRECTIVE_ACTION_GENERATION_SOURCES as r, CORRECTIVE_ACTION_STATUSES as s, type CanonicalId as t, type CarSupportedEvidenceMimeType as u, type CarSupportedSignatureMimeType as v, type CarTemplateFileMetadata as w, CatalogSyncStatus as x, type CatalogSyncStatusType as y, type CompanyConfig as z };
+export { MimeType as $, ACCESS_RANK as A, BarcodeNamespace as B, CAR_SUPPORTED_EVIDENCE_MIME_TYPES as C, type CompanyConfig as D, type CorrectiveActionCompileTaskMetadata as E, type CorrectiveActionGenerationSource as F, type CorrectiveActionStatus as G, CropCycleStatus as H, DOCUMENT_DISPLAY_INFO as I, DOCUMENT_MENU_MAP as J, DocumentCategory as K, DocumentType as L, ERROR_DICTIONARY as M, EVERYONE as N, EmitterType as O, EnabledModule as P, FORM_REGISTRY as Q, FacilityType as R, type FileUploadTaskType as S, type FormMeta as T, HarvestMethod as U, type InfrastructureFields as V, LinkedStatus as W, MOD as X, MODULE_LABELS as Y, type MatrixRow as Z, MicroclimateZone as _, ACT as a, type ModCode as a0, NettingType as a1, type NormalizedSignatureValue as a2, NotificationMode as a3, OrderStatus as a4, type PermissionLevel as a5, PhysicalState as a6, PlantingMethod as a7, type PriceConflictCandidate as a8, type PriceResolutionResult as a9, type StockPolicyTierType as aA, StoragePhases as aB, type StorageType as aC, TASK_TYPE_REGISTRY as aD, TEMPLATE_SCOPE_LEVELS as aE, type TabConfig as aF, TargetEntityType as aG, TaskStatus as aH, TaskType as aI, type TaskTypeConfig as aJ, type TemplateScopeLevel as aK, type Tier as aL, TransactionType as aM, TrellisType as aN, UserPrivilege as aO, type UserPrivilegeType as aP, UserRole as aQ, type UserRoleAssignment as aR, type UserRoleType as aS, VigorRating as aT, WaterSource as aU, type WireSession as aV, type PricingContext as aa, type PricingDataSource as ab, ProductType as ac, type ProductTypeType as ad, ProductUnit as ae, type ProductUnitType as af, RESOURCE_MODULE_MAP as ag, RESOURCE_PATHS as ah, RESOURCE_REQUIREMENTS as ai, ROLE_SECTIONS_BY_KEY as aj, RelationshipType as ak, type ResolvedError as al, type ResourceOverrides as am, type ResourceRequirement as an, type RoleAssignment as ao, RowOrientation as ap, SENTINEL_UUID as aq, SESSION_SCHEMA as ar, SIGNATURE_MODES as as, type SchemaField as at, type ScopeType as au, type ShadowedCleanMatch as av, type SignatureInput as aw, type SignatureMode as ax, SoilTexture as ay, StockPolicyTier as az, AccessLevel as b, type AccessLevelType as c, type AgriCoreSession as d, ApprovalStatus as e, ApprovalType as f, AuditStatus as g, AuditType as h, type AuthScopeFields as i, type AvailableScope as j, type BarcodeNamespaceType as k, BarcodeType as l, type BarcodeTypeType as m, type Base44Id as n, type BaseProductRow as o, CAR_SUPPORTED_SIGNATURE_MIME_TYPES as p, CAT as q, CATEGORY_TABS as r, CORRECTIVE_ACTION_GENERATION_SOURCES as s, CORRECTIVE_ACTION_STATUSES as t, type CanonicalId as u, type CarSupportedEvidenceMimeType as v, type CarSupportedSignatureMimeType as w, type CarTemplateFileMetadata as x, CatalogSyncStatus as y, type CatalogSyncStatusType as z };

package/dist/{constants-C0zV05Cf.d.ts → constants-CrAPx_xU.d.ts}

@@ -206,6 +206,66 @@ type ProductUnitType = typeof ProductUnit[keyof typeof ProductUnit];
 type CatalogSyncStatusType = typeof CatalogSyncStatus[keyof typeof CatalogSyncStatus];
 type StorageType = typeof StoragePhases[keyof typeof StoragePhases];
 type StockPolicyTierType = typeof StockPolicyTier[keyof typeof StockPolicyTier];
+interface PricingContext {
+    productId: string;
+    companyId: string;
+    facilityId?: string;
+    accountCode?: string | null;
+    contractReferenceNumber?: string | null;
+    evaluationDate?: Date;
+}
+interface PriceResolutionResult {
+    unitPriceCents: number;
+    minimumOrderQuantity: number;
+    leadTimeDays: number | null;
+    priceSource: 'EXPLICIT_CONTRACT' | 'ACCOUNT_MATRIX' | 'INTERNAL_DEFAULT' | 'PRODUCT_FALLBACK';
+    sourceRecordId: string;
+}
+interface PricingDataSource {
+    findContractPrice(args: {
+        productId: string;
+        contractReferenceNumber: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findAccountPrice(args: {
+        productId: string;
+        accountCode: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findDefaultPrice(args: {
+        productId: string;
+        targetDate: Date;
+    }): Promise<MatrixRow | null>;
+    findBaseProduct(args: {
+        productId: string;
+    }): Promise<BaseProductRow | null>;
+}
+interface MatrixRow {
+    canonicalId: string;
+    matrixUnitPriceCents: number;
+    minimumOrderQuantity: number;
+    leadTimeDays: number | null;
+}
+interface BaseProductRow {
+    canonicalId: string;
+    unitPriceCents: number;
+}
+type Tier = 'EXPLICIT_CONTRACT' | 'ACCOUNT_MATRIX' | 'INTERNAL_DEFAULT';
+interface PriceConflictCandidate {
+    sourceRecordId: string;
+    unitPriceCents: number;
+    validFrom: string;
+    validTo: string | null;
+}
+interface ShadowedCleanMatch {
+    tier: Tier;
+    unitPriceCents: number;
+    sourceRecordId: string;
+    matchedOn: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    };
+}
 
 declare const MOD: {
     readonly OPERATIONS: "OPR";
@@ -686,4 +746,4 @@ declare const StockPolicyTier: {
     readonly BY_LOCATION: 3;
 };
 
-export { NettingType as $, ACCESS_RANK as A, BarcodeNamespace as B, CAR_SUPPORTED_EVIDENCE_MIME_TYPES as C, type CorrectiveActionCompileTaskMetadata as D, type CorrectiveActionGenerationSource as E, type CorrectiveActionStatus as F, CropCycleStatus as G, DOCUMENT_DISPLAY_INFO as H, DOCUMENT_MENU_MAP as I, DocumentCategory as J, DocumentType as K, ERROR_DICTIONARY as L, EVERYONE as M, EmitterType as N, EnabledModule as O, FORM_REGISTRY as P, FacilityType as Q, type FileUploadTaskType as R, type FormMeta as S, HarvestMethod as T, type InfrastructureFields as U, LinkedStatus as V, MOD as W, MODULE_LABELS as X, MicroclimateZone as Y, MimeType as Z, type ModCode as _, ACT as a, type NormalizedSignatureValue as a0, NotificationMode as a1, OrderStatus as a2, type PermissionLevel as a3, PhysicalState as a4, PlantingMethod as a5, ProductType as a6, type ProductTypeType as a7, ProductUnit as a8, type ProductUnitType as a9, TaskStatus as aA, TaskType as aB, type TaskTypeConfig as aC, type TemplateScopeLevel as aD, TransactionType as aE, TrellisType as aF, UserPrivilege as aG, type UserPrivilegeType as aH, UserRole as aI, type UserRoleAssignment as aJ, type UserRoleType as aK, VigorRating as aL, WaterSource as aM, type WireSession as aN, RESOURCE_MODULE_MAP as aa, RESOURCE_PATHS as ab, RESOURCE_REQUIREMENTS as ac, ROLE_SECTIONS_BY_KEY as ad, RelationshipType as ae, type ResolvedError as af, type ResourceOverrides as ag, type ResourceRequirement as ah, type RoleAssignment as ai, RowOrientation as aj, SENTINEL_UUID as ak, SESSION_SCHEMA as al, SIGNATURE_MODES as am, type SchemaField as an, type ScopeType as ao, type SignatureInput as ap, type SignatureMode as aq, SoilTexture as ar, StockPolicyTier as as, type StockPolicyTierType as at, StoragePhases as au, type StorageType as av, TASK_TYPE_REGISTRY as aw, TEMPLATE_SCOPE_LEVELS as ax, type TabConfig as ay, TargetEntityType as az, AccessLevel as b, type AccessLevelType as c, type AgriCoreSession as d, ApprovalStatus as e, ApprovalType as f, AuditStatus as g, AuditType as h, type AuthScopeFields as i, type AvailableScope as j, type BarcodeNamespaceType as k, BarcodeType as l, type BarcodeTypeType as m, type Base44Id as n, CAR_SUPPORTED_SIGNATURE_MIME_TYPES as o, CAT as p, CATEGORY_TABS as q, CORRECTIVE_ACTION_GENERATION_SOURCES as r, CORRECTIVE_ACTION_STATUSES as s, type CanonicalId as t, type CarSupportedEvidenceMimeType as u, type CarSupportedSignatureMimeType as v, type CarTemplateFileMetadata as w, CatalogSyncStatus as x, type CatalogSyncStatusType as y, type CompanyConfig as z };
+export { MimeType as $, ACCESS_RANK as A, BarcodeNamespace as B, CAR_SUPPORTED_EVIDENCE_MIME_TYPES as C, type CompanyConfig as D, type CorrectiveActionCompileTaskMetadata as E, type CorrectiveActionGenerationSource as F, type CorrectiveActionStatus as G, CropCycleStatus as H, DOCUMENT_DISPLAY_INFO as I, DOCUMENT_MENU_MAP as J, DocumentCategory as K, DocumentType as L, ERROR_DICTIONARY as M, EVERYONE as N, EmitterType as O, EnabledModule as P, FORM_REGISTRY as Q, FacilityType as R, type FileUploadTaskType as S, type FormMeta as T, HarvestMethod as U, type InfrastructureFields as V, LinkedStatus as W, MOD as X, MODULE_LABELS as Y, type MatrixRow as Z, MicroclimateZone as _, ACT as a, type ModCode as a0, NettingType as a1, type NormalizedSignatureValue as a2, NotificationMode as a3, OrderStatus as a4, type PermissionLevel as a5, PhysicalState as a6, PlantingMethod as a7, type PriceConflictCandidate as a8, type PriceResolutionResult as a9, type StockPolicyTierType as aA, StoragePhases as aB, type StorageType as aC, TASK_TYPE_REGISTRY as aD, TEMPLATE_SCOPE_LEVELS as aE, type TabConfig as aF, TargetEntityType as aG, TaskStatus as aH, TaskType as aI, type TaskTypeConfig as aJ, type TemplateScopeLevel as aK, type Tier as aL, TransactionType as aM, TrellisType as aN, UserPrivilege as aO, type UserPrivilegeType as aP, UserRole as aQ, type UserRoleAssignment as aR, type UserRoleType as aS, VigorRating as aT, WaterSource as aU, type WireSession as aV, type PricingContext as aa, type PricingDataSource as ab, ProductType as ac, type ProductTypeType as ad, ProductUnit as ae, type ProductUnitType as af, RESOURCE_MODULE_MAP as ag, RESOURCE_PATHS as ah, RESOURCE_REQUIREMENTS as ai, ROLE_SECTIONS_BY_KEY as aj, RelationshipType as ak, type ResolvedError as al, type ResourceOverrides as am, type ResourceRequirement as an, type RoleAssignment as ao, RowOrientation as ap, SENTINEL_UUID as aq, SESSION_SCHEMA as ar, SIGNATURE_MODES as as, type SchemaField as at, type ScopeType as au, type ShadowedCleanMatch as av, type SignatureInput as aw, type SignatureMode as ax, SoilTexture as ay, StockPolicyTier as az, AccessLevel as b, type AccessLevelType as c, type AgriCoreSession as d, ApprovalStatus as e, ApprovalType as f, AuditStatus as g, AuditType as h, type AuthScopeFields as i, type AvailableScope as j, type BarcodeNamespaceType as k, BarcodeType as l, type BarcodeTypeType as m, type Base44Id as n, type BaseProductRow as o, CAR_SUPPORTED_SIGNATURE_MIME_TYPES as p, CAT as q, CATEGORY_TABS as r, CORRECTIVE_ACTION_GENERATION_SOURCES as s, CORRECTIVE_ACTION_STATUSES as t, type CanonicalId as u, type CarSupportedEvidenceMimeType as v, type CarSupportedSignatureMimeType as w, type CarTemplateFileMetadata as x, CatalogSyncStatus as y, type CatalogSyncStatusType as z };

package/dist/constants.d.mts

@@ -1 +1 @@
-export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, B as BarcodeNamespace, l as BarcodeType, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, o as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, p as CAT, q as CATEGORY_TABS, r as CORRECTIVE_ACTION_GENERATION_SOURCES, s as CORRECTIVE_ACTION_STATUSES, x as CatalogSyncStatus, G as CropCycleStatus, H as DOCUMENT_DISPLAY_INFO, I as DOCUMENT_MENU_MAP, J as DocumentCategory, K as DocumentType, L as ERROR_DICTIONARY, M as EVERYONE, N as EmitterType, O as EnabledModule, P as FORM_REGISTRY, Q as FacilityType, T as HarvestMethod, V as LinkedStatus, W as MOD, X as MODULE_LABELS, Y as MicroclimateZone, Z as MimeType, _ as ModCode, $ as NettingType, a1 as NotificationMode, a2 as OrderStatus, a4 as PhysicalState, a5 as PlantingMethod, a6 as ProductType, a8 as ProductUnit, aa as RESOURCE_MODULE_MAP, ab as RESOURCE_PATHS, ac as RESOURCE_REQUIREMENTS, ad as ROLE_SECTIONS_BY_KEY, ae as RelationshipType, ah as ResourceRequirement, aj as RowOrientation, ak as SENTINEL_UUID, al as SESSION_SCHEMA, am as SIGNATURE_MODES, ar as SoilTexture, as as StockPolicyTier, au as StoragePhases, aw as TASK_TYPE_REGISTRY, ax as TEMPLATE_SCOPE_LEVELS, az as TargetEntityType, aA as TaskStatus, aB as TaskType, aE as TransactionType, aF as TrellisType, aG as UserPrivilege, aI as UserRole, aL as VigorRating, aM as WaterSource } from './constants-C0zV05Cf.mjs';
+export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, B as BarcodeNamespace, l as BarcodeType, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, p as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, q as CAT, r as CATEGORY_TABS, s as CORRECTIVE_ACTION_GENERATION_SOURCES, t as CORRECTIVE_ACTION_STATUSES, y as CatalogSyncStatus, H as CropCycleStatus, I as DOCUMENT_DISPLAY_INFO, J as DOCUMENT_MENU_MAP, K as DocumentCategory, L as DocumentType, M as ERROR_DICTIONARY, N as EVERYONE, O as EmitterType, P as EnabledModule, Q as FORM_REGISTRY, R as FacilityType, U as HarvestMethod, W as LinkedStatus, X as MOD, Y as MODULE_LABELS, _ as MicroclimateZone, $ as MimeType, a0 as ModCode, a1 as NettingType, a3 as NotificationMode, a4 as OrderStatus, a6 as PhysicalState, a7 as PlantingMethod, ac as ProductType, ae as ProductUnit, ag as RESOURCE_MODULE_MAP, ah as RESOURCE_PATHS, ai as RESOURCE_REQUIREMENTS, aj as ROLE_SECTIONS_BY_KEY, ak as RelationshipType, an as ResourceRequirement, ap as RowOrientation, aq as SENTINEL_UUID, ar as SESSION_SCHEMA, as as SIGNATURE_MODES, ay as SoilTexture, az as StockPolicyTier, aB as StoragePhases, aD as TASK_TYPE_REGISTRY, aE as TEMPLATE_SCOPE_LEVELS, aG as TargetEntityType, aH as TaskStatus, aI as TaskType, aM as TransactionType, aN as TrellisType, aO as UserPrivilege, aQ as UserRole, aT as VigorRating, aU as WaterSource } from './constants-CrAPx_xU.mjs';

package/dist/constants.d.ts

@@ -1 +1 @@
-export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, B as BarcodeNamespace, l as BarcodeType, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, o as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, p as CAT, q as CATEGORY_TABS, r as CORRECTIVE_ACTION_GENERATION_SOURCES, s as CORRECTIVE_ACTION_STATUSES, x as CatalogSyncStatus, G as CropCycleStatus, H as DOCUMENT_DISPLAY_INFO, I as DOCUMENT_MENU_MAP, J as DocumentCategory, K as DocumentType, L as ERROR_DICTIONARY, M as EVERYONE, N as EmitterType, O as EnabledModule, P as FORM_REGISTRY, Q as FacilityType, T as HarvestMethod, V as LinkedStatus, W as MOD, X as MODULE_LABELS, Y as MicroclimateZone, Z as MimeType, _ as ModCode, $ as NettingType, a1 as NotificationMode, a2 as OrderStatus, a4 as PhysicalState, a5 as PlantingMethod, a6 as ProductType, a8 as ProductUnit, aa as RESOURCE_MODULE_MAP, ab as RESOURCE_PATHS, ac as RESOURCE_REQUIREMENTS, ad as ROLE_SECTIONS_BY_KEY, ae as RelationshipType, ah as ResourceRequirement, aj as RowOrientation, ak as SENTINEL_UUID, al as SESSION_SCHEMA, am as SIGNATURE_MODES, ar as SoilTexture, as as StockPolicyTier, au as StoragePhases, aw as TASK_TYPE_REGISTRY, ax as TEMPLATE_SCOPE_LEVELS, az as TargetEntityType, aA as TaskStatus, aB as TaskType, aE as TransactionType, aF as TrellisType, aG as UserPrivilege, aI as UserRole, aL as VigorRating, aM as WaterSource } from './constants-C0zV05Cf.js';
+export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, B as BarcodeNamespace, l as BarcodeType, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, p as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, q as CAT, r as CATEGORY_TABS, s as CORRECTIVE_ACTION_GENERATION_SOURCES, t as CORRECTIVE_ACTION_STATUSES, y as CatalogSyncStatus, H as CropCycleStatus, I as DOCUMENT_DISPLAY_INFO, J as DOCUMENT_MENU_MAP, K as DocumentCategory, L as DocumentType, M as ERROR_DICTIONARY, N as EVERYONE, O as EmitterType, P as EnabledModule, Q as FORM_REGISTRY, R as FacilityType, U as HarvestMethod, W as LinkedStatus, X as MOD, Y as MODULE_LABELS, _ as MicroclimateZone, $ as MimeType, a0 as ModCode, a1 as NettingType, a3 as NotificationMode, a4 as OrderStatus, a6 as PhysicalState, a7 as PlantingMethod, ac as ProductType, ae as ProductUnit, ag as RESOURCE_MODULE_MAP, ah as RESOURCE_PATHS, ai as RESOURCE_REQUIREMENTS, aj as ROLE_SECTIONS_BY_KEY, ak as RelationshipType, an as ResourceRequirement, ap as RowOrientation, aq as SENTINEL_UUID, ar as SESSION_SCHEMA, as as SIGNATURE_MODES, ay as SoilTexture, az as StockPolicyTier, aB as StoragePhases, aD as TASK_TYPE_REGISTRY, aE as TEMPLATE_SCOPE_LEVELS, aG as TargetEntityType, aH as TaskStatus, aI as TaskType, aM as TransactionType, aN as TrellisType, aO as UserPrivilege, aQ as UserRole, aT as VigorRating, aU as WaterSource } from './constants-CrAPx_xU.js';

package/dist/constants.js

@@ -150,7 +150,8 @@ var ERROR_DICTIONARY = {
   "400": { title: "Data Conflict", text: "A conflict occurred with an existing record. Please review and try again." },
   "402": { title: "Duplicate Entry", text: "A record with this name or identifier already exists." },
   "403": { title: "Edit Conflict", text: "This record was recently updated by someone else. Please refresh and try again." },
-  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." }
+  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." },
+  "405": { title: "Pricing Conflict", text: "Multiple active prices were found for this product. An administrator must resolve the conflict before this price can be used." }
 };
 var UserRole = {
   OWNER: "owner",

package/dist/constants.mjs

@@ -62,7 +62,7 @@ import {
   UserRole,
   VigorRating,
   WaterSource
-} from "./chunk-GZRAFNPA.mjs";
+} from "./chunk-Y5KVDVNY.mjs";
 export {
   ACCESS_RANK,
   ACT,

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { d as AgriCoreSession, aJ as UserRoleAssignment, ao as ScopeType, aN as WireSession, ah as ResourceRequirement, c as AccessLevelType, j as AvailableScope, U as InfrastructureFields, S as FormMeta, ay as TabConfig, af as ResolvedError } from './constants-C0zV05Cf.mjs';
-export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, i as AuthScopeFields, B as BarcodeNamespace, k as BarcodeNamespaceType, l as BarcodeType, m as BarcodeTypeType, n as Base44Id, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, o as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, p as CAT, q as CATEGORY_TABS, r as CORRECTIVE_ACTION_GENERATION_SOURCES, s as CORRECTIVE_ACTION_STATUSES, t as CanonicalId, u as CarSupportedEvidenceMimeType, v as CarSupportedSignatureMimeType, w as CarTemplateFileMetadata, x as CatalogSyncStatus, y as CatalogSyncStatusType, z as CompanyConfig, D as CorrectiveActionCompileTaskMetadata, E as CorrectiveActionGenerationSource, F as CorrectiveActionStatus, G as CropCycleStatus, H as DOCUMENT_DISPLAY_INFO, I as DOCUMENT_MENU_MAP, J as DocumentCategory, K as DocumentType, L as ERROR_DICTIONARY, M as EVERYONE, N as EmitterType, O as EnabledModule, P as FORM_REGISTRY, Q as FacilityType, R as FileUploadTaskType, T as HarvestMethod, V as LinkedStatus, W as MOD, X as MODULE_LABELS, Y as MicroclimateZone, Z as MimeType, _ as ModCode, $ as NettingType, a0 as NormalizedSignatureValue, a1 as NotificationMode, a2 as OrderStatus, a3 as PermissionLevel, a4 as PhysicalState, a5 as PlantingMethod, a6 as ProductType, a7 as ProductTypeType, a8 as ProductUnit, a9 as ProductUnitType, aa as RESOURCE_MODULE_MAP, ab as RESOURCE_PATHS, ac as RESOURCE_REQUIREMENTS, ad as ROLE_SECTIONS_BY_KEY, ae as RelationshipType, ag as ResourceOverrides, ai as RoleAssignment, aj as RowOrientation, ak as SENTINEL_UUID, al as SESSION_SCHEMA, am as SIGNATURE_MODES, an as SchemaField, ap as SignatureInput, aq as SignatureMode, ar as SoilTexture, as as StockPolicyTier, at as StockPolicyTierType, au as StoragePhases, av as StorageType, aw as TASK_TYPE_REGISTRY, ax as TEMPLATE_SCOPE_LEVELS, az as TargetEntityType, aA as TaskStatus, aB as TaskType, aC as TaskTypeConfig, aD as TemplateScopeLevel, aE as TransactionType, aF as TrellisType, aG as UserPrivilege, aH as UserPrivilegeType, aI as UserRole, aK as UserRoleType, aL as VigorRating, aM as WaterSource } from './constants-C0zV05Cf.mjs';
+import { d as AgriCoreSession, aR as UserRoleAssignment, aL as Tier, a8 as PriceConflictCandidate, av as ShadowedCleanMatch, ab as PricingDataSource, aa as PricingContext, a9 as PriceResolutionResult, au as ScopeType, aV as WireSession, an as ResourceRequirement, c as AccessLevelType, j as AvailableScope, V as InfrastructureFields, T as FormMeta, aF as TabConfig, al as ResolvedError } from './constants-CrAPx_xU.mjs';
+export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, i as AuthScopeFields, B as BarcodeNamespace, k as BarcodeNamespaceType, l as BarcodeType, m as BarcodeTypeType, n as Base44Id, o as BaseProductRow, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, p as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, q as CAT, r as CATEGORY_TABS, s as CORRECTIVE_ACTION_GENERATION_SOURCES, t as CORRECTIVE_ACTION_STATUSES, u as CanonicalId, v as CarSupportedEvidenceMimeType, w as CarSupportedSignatureMimeType, x as CarTemplateFileMetadata, y as CatalogSyncStatus, z as CatalogSyncStatusType, D as CompanyConfig, E as CorrectiveActionCompileTaskMetadata, F as CorrectiveActionGenerationSource, G as CorrectiveActionStatus, H as CropCycleStatus, I as DOCUMENT_DISPLAY_INFO, J as DOCUMENT_MENU_MAP, K as DocumentCategory, L as DocumentType, M as ERROR_DICTIONARY, N as EVERYONE, O as EmitterType, P as EnabledModule, Q as FORM_REGISTRY, R as FacilityType, S as FileUploadTaskType, U as HarvestMethod, W as LinkedStatus, X as MOD, Y as MODULE_LABELS, Z as MatrixRow, _ as MicroclimateZone, $ as MimeType, a0 as ModCode, a1 as NettingType, a2 as NormalizedSignatureValue, a3 as NotificationMode, a4 as OrderStatus, a5 as PermissionLevel, a6 as PhysicalState, a7 as PlantingMethod, ac as ProductType, ad as ProductTypeType, ae as ProductUnit, af as ProductUnitType, ag as RESOURCE_MODULE_MAP, ah as RESOURCE_PATHS, ai as RESOURCE_REQUIREMENTS, aj as ROLE_SECTIONS_BY_KEY, ak as RelationshipType, am as ResourceOverrides, ao as RoleAssignment, ap as RowOrientation, aq as SENTINEL_UUID, ar as SESSION_SCHEMA, as as SIGNATURE_MODES, at as SchemaField, aw as SignatureInput, ax as SignatureMode, ay as SoilTexture, az as StockPolicyTier, aA as StockPolicyTierType, aB as StoragePhases, aC as StorageType, aD as TASK_TYPE_REGISTRY, aE as TEMPLATE_SCOPE_LEVELS, aG as TargetEntityType, aH as TaskStatus, aI as TaskType, aJ as TaskTypeConfig, aK as TemplateScopeLevel, aM as TransactionType, aN as TrellisType, aO as UserPrivilege, aP as UserPrivilegeType, aQ as UserRole, aS as UserRoleType, aT as VigorRating, aU as WaterSource } from './constants-CrAPx_xU.mjs';
 
 declare const AgriLogger: {
     log(level: "INFO" | "WARN" | "ERROR", message: string, meta: any): void;
@@ -18,6 +18,42 @@ declare function transformRoleAssignments(assignments: UserRoleAssignment[]): Re
     privileges: string[];
 }>;
 
+declare class PriceAmbiguityError extends Error {
+    readonly productId: string;
+    readonly tier: Tier;
+    readonly candidates: PriceConflictCandidate[];
+    readonly matchedOn: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    };
+    constructor(productId: string, tier: Tier, candidates: PriceConflictCandidate[], matchedOn?: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    });
+}
+declare class AggregatePriceAmbiguityError extends Error {
+    readonly productId: string;
+    readonly conflicts: PriceAmbiguityError[];
+    readonly shadowedCleanMatches: ShadowedCleanMatch[];
+    constructor(productId: string, conflicts: PriceAmbiguityError[], shadowedCleanMatches?: ShadowedCleanMatch[]);
+}
+declare function resolvePrice(dataSource: PricingDataSource, context: PricingContext): Promise<PriceResolutionResult>;
+interface PricingAdapterScope {
+    authScopeId: string;
+    companyId?: string;
+}
+declare function createBase44PricingAdapter(db: any, scope: PricingAdapterScope): PricingDataSource;
+interface OverlapCheckScope extends PricingAdapterScope {
+    productId: string;
+    accountCode?: string;
+    contractReferenceNumber?: string;
+    matrixType?: 'procurement_buy' | 'contract_packing_charge';
+}
+declare function findOverlappingPriceWindows(db: any, scope: OverlapCheckScope, newRow: {
+    validFrom: string;
+    validTo: string | null;
+}, excludeId?: string): Promise<PriceConflictCandidate[]>;
+
 declare const Validator: {
     /** * 1. Email: The classic. Uses a standard RFC 5322 regex.
      */
@@ -84,15 +120,16 @@ declare class AppError extends Error {
     status: number;
     appCode: string;
     isOperational: boolean;
-    constructor(status: number, mod: string, cat: string, act: string, message: string);
+    details?: unknown;
+    constructor(status: number, mod: string, cat: string, act: string, message: string, details?: unknown);
 }
 declare const ErrorFactory: {
     unauthorized: (mod: string, msg?: string) => AppError;
     forbidden: (mod: string, act: string, msg?: string) => AppError;
     badRequest: (mod: string, act: string, msg?: string) => AppError;
     notFound: (mod: string, act?: "00", msg?: string) => AppError;
-    conflict: (mod: string, act: string, msg?: string) => AppError;
-    integrity: (mod: string, act?: "00", msg?: string) => AppError;
+    conflict: (mod: string, act: string, msg?: string, details?: unknown) => AppError;
+    integrity: (mod: string, act?: "00", msg?: string, details?: unknown) => AppError;
     subscription: (mod: string, msg?: string) => AppError;
     internal: (mod: string, msg?: string) => AppError;
 };
@@ -178,4 +215,4 @@ declare function calculateFileMetadataMatch(criteria: {
     contextMatch?: string[];
 }, fileMetadata: Record<string, any>, auditContext: Record<string, any>): number;
 
-export { AccessLevelType, AgriCoreSession, AgriLogger, AppError, AvailableScope, Converter, ErrorFactory, FormMeta, InfrastructureFields, ResolvedError, ResourceRequirement, ScopeType, TabConfig, UserRoleAssignment, Validator, WireSession, assertTenantBoundary, calculateFileMetadataMatch, decodeSession, encodeSession, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getPrivilegesAt, getRoleAt, getScopeAncestry, getTaskTypeOptions, handleAppErrorResponse, hasPrivilegeAt, hasRoleAt, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, transformRoleAssignments, verifyAndExtractSession, withAgriLogging };
+export { AccessLevelType, AggregatePriceAmbiguityError, AgriCoreSession, AgriLogger, AppError, AvailableScope, Converter, ErrorFactory, FormMeta, InfrastructureFields, type OverlapCheckScope, PriceAmbiguityError, PriceConflictCandidate, PriceResolutionResult, type PricingAdapterScope, PricingContext, PricingDataSource, ResolvedError, ResourceRequirement, ScopeType, ShadowedCleanMatch, TabConfig, Tier, UserRoleAssignment, Validator, WireSession, assertTenantBoundary, calculateFileMetadataMatch, createBase44PricingAdapter, decodeSession, encodeSession, evaluateBaseAccess, extractAppCode, findOverlappingPriceWindows, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getPrivilegesAt, getRoleAt, getScopeAncestry, getTaskTypeOptions, handleAppErrorResponse, hasPrivilegeAt, hasRoleAt, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolvePrice, transformRoleAssignments, verifyAndExtractSession, withAgriLogging };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { d as AgriCoreSession, aJ as UserRoleAssignment, ao as ScopeType, aN as WireSession, ah as ResourceRequirement, c as AccessLevelType, j as AvailableScope, U as InfrastructureFields, S as FormMeta, ay as TabConfig, af as ResolvedError } from './constants-C0zV05Cf.js';
-export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, i as AuthScopeFields, B as BarcodeNamespace, k as BarcodeNamespaceType, l as BarcodeType, m as BarcodeTypeType, n as Base44Id, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, o as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, p as CAT, q as CATEGORY_TABS, r as CORRECTIVE_ACTION_GENERATION_SOURCES, s as CORRECTIVE_ACTION_STATUSES, t as CanonicalId, u as CarSupportedEvidenceMimeType, v as CarSupportedSignatureMimeType, w as CarTemplateFileMetadata, x as CatalogSyncStatus, y as CatalogSyncStatusType, z as CompanyConfig, D as CorrectiveActionCompileTaskMetadata, E as CorrectiveActionGenerationSource, F as CorrectiveActionStatus, G as CropCycleStatus, H as DOCUMENT_DISPLAY_INFO, I as DOCUMENT_MENU_MAP, J as DocumentCategory, K as DocumentType, L as ERROR_DICTIONARY, M as EVERYONE, N as EmitterType, O as EnabledModule, P as FORM_REGISTRY, Q as FacilityType, R as FileUploadTaskType, T as HarvestMethod, V as LinkedStatus, W as MOD, X as MODULE_LABELS, Y as MicroclimateZone, Z as MimeType, _ as ModCode, $ as NettingType, a0 as NormalizedSignatureValue, a1 as NotificationMode, a2 as OrderStatus, a3 as PermissionLevel, a4 as PhysicalState, a5 as PlantingMethod, a6 as ProductType, a7 as ProductTypeType, a8 as ProductUnit, a9 as ProductUnitType, aa as RESOURCE_MODULE_MAP, ab as RESOURCE_PATHS, ac as RESOURCE_REQUIREMENTS, ad as ROLE_SECTIONS_BY_KEY, ae as RelationshipType, ag as ResourceOverrides, ai as RoleAssignment, aj as RowOrientation, ak as SENTINEL_UUID, al as SESSION_SCHEMA, am as SIGNATURE_MODES, an as SchemaField, ap as SignatureInput, aq as SignatureMode, ar as SoilTexture, as as StockPolicyTier, at as StockPolicyTierType, au as StoragePhases, av as StorageType, aw as TASK_TYPE_REGISTRY, ax as TEMPLATE_SCOPE_LEVELS, az as TargetEntityType, aA as TaskStatus, aB as TaskType, aC as TaskTypeConfig, aD as TemplateScopeLevel, aE as TransactionType, aF as TrellisType, aG as UserPrivilege, aH as UserPrivilegeType, aI as UserRole, aK as UserRoleType, aL as VigorRating, aM as WaterSource } from './constants-C0zV05Cf.js';
+import { d as AgriCoreSession, aR as UserRoleAssignment, aL as Tier, a8 as PriceConflictCandidate, av as ShadowedCleanMatch, ab as PricingDataSource, aa as PricingContext, a9 as PriceResolutionResult, au as ScopeType, aV as WireSession, an as ResourceRequirement, c as AccessLevelType, j as AvailableScope, V as InfrastructureFields, T as FormMeta, aF as TabConfig, al as ResolvedError } from './constants-CrAPx_xU.js';
+export { A as ACCESS_RANK, a as ACT, b as AccessLevel, e as ApprovalStatus, f as ApprovalType, g as AuditStatus, h as AuditType, i as AuthScopeFields, B as BarcodeNamespace, k as BarcodeNamespaceType, l as BarcodeType, m as BarcodeTypeType, n as Base44Id, o as BaseProductRow, C as CAR_SUPPORTED_EVIDENCE_MIME_TYPES, p as CAR_SUPPORTED_SIGNATURE_MIME_TYPES, q as CAT, r as CATEGORY_TABS, s as CORRECTIVE_ACTION_GENERATION_SOURCES, t as CORRECTIVE_ACTION_STATUSES, u as CanonicalId, v as CarSupportedEvidenceMimeType, w as CarSupportedSignatureMimeType, x as CarTemplateFileMetadata, y as CatalogSyncStatus, z as CatalogSyncStatusType, D as CompanyConfig, E as CorrectiveActionCompileTaskMetadata, F as CorrectiveActionGenerationSource, G as CorrectiveActionStatus, H as CropCycleStatus, I as DOCUMENT_DISPLAY_INFO, J as DOCUMENT_MENU_MAP, K as DocumentCategory, L as DocumentType, M as ERROR_DICTIONARY, N as EVERYONE, O as EmitterType, P as EnabledModule, Q as FORM_REGISTRY, R as FacilityType, S as FileUploadTaskType, U as HarvestMethod, W as LinkedStatus, X as MOD, Y as MODULE_LABELS, Z as MatrixRow, _ as MicroclimateZone, $ as MimeType, a0 as ModCode, a1 as NettingType, a2 as NormalizedSignatureValue, a3 as NotificationMode, a4 as OrderStatus, a5 as PermissionLevel, a6 as PhysicalState, a7 as PlantingMethod, ac as ProductType, ad as ProductTypeType, ae as ProductUnit, af as ProductUnitType, ag as RESOURCE_MODULE_MAP, ah as RESOURCE_PATHS, ai as RESOURCE_REQUIREMENTS, aj as ROLE_SECTIONS_BY_KEY, ak as RelationshipType, am as ResourceOverrides, ao as RoleAssignment, ap as RowOrientation, aq as SENTINEL_UUID, ar as SESSION_SCHEMA, as as SIGNATURE_MODES, at as SchemaField, aw as SignatureInput, ax as SignatureMode, ay as SoilTexture, az as StockPolicyTier, aA as StockPolicyTierType, aB as StoragePhases, aC as StorageType, aD as TASK_TYPE_REGISTRY, aE as TEMPLATE_SCOPE_LEVELS, aG as TargetEntityType, aH as TaskStatus, aI as TaskType, aJ as TaskTypeConfig, aK as TemplateScopeLevel, aM as TransactionType, aN as TrellisType, aO as UserPrivilege, aP as UserPrivilegeType, aQ as UserRole, aS as UserRoleType, aT as VigorRating, aU as WaterSource } from './constants-CrAPx_xU.js';
 
 declare const AgriLogger: {
     log(level: "INFO" | "WARN" | "ERROR", message: string, meta: any): void;
@@ -18,6 +18,42 @@ declare function transformRoleAssignments(assignments: UserRoleAssignment[]): Re
     privileges: string[];
 }>;
 
+declare class PriceAmbiguityError extends Error {
+    readonly productId: string;
+    readonly tier: Tier;
+    readonly candidates: PriceConflictCandidate[];
+    readonly matchedOn: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    };
+    constructor(productId: string, tier: Tier, candidates: PriceConflictCandidate[], matchedOn?: {
+        accountCode?: string;
+        contractReferenceNumber?: string;
+    });
+}
+declare class AggregatePriceAmbiguityError extends Error {
+    readonly productId: string;
+    readonly conflicts: PriceAmbiguityError[];
+    readonly shadowedCleanMatches: ShadowedCleanMatch[];
+    constructor(productId: string, conflicts: PriceAmbiguityError[], shadowedCleanMatches?: ShadowedCleanMatch[]);
+}
+declare function resolvePrice(dataSource: PricingDataSource, context: PricingContext): Promise<PriceResolutionResult>;
+interface PricingAdapterScope {
+    authScopeId: string;
+    companyId?: string;
+}
+declare function createBase44PricingAdapter(db: any, scope: PricingAdapterScope): PricingDataSource;
+interface OverlapCheckScope extends PricingAdapterScope {
+    productId: string;
+    accountCode?: string;
+    contractReferenceNumber?: string;
+    matrixType?: 'procurement_buy' | 'contract_packing_charge';
+}
+declare function findOverlappingPriceWindows(db: any, scope: OverlapCheckScope, newRow: {
+    validFrom: string;
+    validTo: string | null;
+}, excludeId?: string): Promise<PriceConflictCandidate[]>;
+
 declare const Validator: {
     /** * 1. Email: The classic. Uses a standard RFC 5322 regex.
      */
@@ -84,15 +120,16 @@ declare class AppError extends Error {
     status: number;
     appCode: string;
     isOperational: boolean;
-    constructor(status: number, mod: string, cat: string, act: string, message: string);
+    details?: unknown;
+    constructor(status: number, mod: string, cat: string, act: string, message: string, details?: unknown);
 }
 declare const ErrorFactory: {
     unauthorized: (mod: string, msg?: string) => AppError;
     forbidden: (mod: string, act: string, msg?: string) => AppError;
     badRequest: (mod: string, act: string, msg?: string) => AppError;
     notFound: (mod: string, act?: "00", msg?: string) => AppError;
-    conflict: (mod: string, act: string, msg?: string) => AppError;
-    integrity: (mod: string, act?: "00", msg?: string) => AppError;
+    conflict: (mod: string, act: string, msg?: string, details?: unknown) => AppError;
+    integrity: (mod: string, act?: "00", msg?: string, details?: unknown) => AppError;
     subscription: (mod: string, msg?: string) => AppError;
     internal: (mod: string, msg?: string) => AppError;
 };
@@ -178,4 +215,4 @@ declare function calculateFileMetadataMatch(criteria: {
     contextMatch?: string[];
 }, fileMetadata: Record<string, any>, auditContext: Record<string, any>): number;
 
-export { AccessLevelType, AgriCoreSession, AgriLogger, AppError, AvailableScope, Converter, ErrorFactory, FormMeta, InfrastructureFields, ResolvedError, ResourceRequirement, ScopeType, TabConfig, UserRoleAssignment, Validator, WireSession, assertTenantBoundary, calculateFileMetadataMatch, decodeSession, encodeSession, evaluateBaseAccess, extractAppCode, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getPrivilegesAt, getRoleAt, getScopeAncestry, getTaskTypeOptions, handleAppErrorResponse, hasPrivilegeAt, hasRoleAt, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, transformRoleAssignments, verifyAndExtractSession, withAgriLogging };
+export { AccessLevelType, AggregatePriceAmbiguityError, AgriCoreSession, AgriLogger, AppError, AvailableScope, Converter, ErrorFactory, FormMeta, InfrastructureFields, type OverlapCheckScope, PriceAmbiguityError, PriceConflictCandidate, PriceResolutionResult, type PricingAdapterScope, PricingContext, PricingDataSource, ResolvedError, ResourceRequirement, ScopeType, ShadowedCleanMatch, TabConfig, Tier, UserRoleAssignment, Validator, WireSession, assertTenantBoundary, calculateFileMetadataMatch, createBase44PricingAdapter, decodeSession, encodeSession, evaluateBaseAccess, extractAppCode, findOverlappingPriceWindows, findSpecificOverride, generateCanonicalId, generateDocumentPath, generateInfrastructureFields, getAcceptedMimeTypes, getApproveAction, getFormMeta, getFormsGroupedByModule, getPrivilegesAt, getRoleAt, getScopeAncestry, getTaskTypeOptions, handleAppErrorResponse, hasPrivilegeAt, hasRoleAt, isTabVisible, isTabWritable, resolveAccess, resolveAppError, resolveEffectiveAccess, resolveError, resolvePrice, transformRoleAssignments, verifyAndExtractSession, withAgriLogging };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   ACCESS_RANK: () => ACCESS_RANK,
   ACT: () => ACT,
   AccessLevel: () => AccessLevel,
+  AggregatePriceAmbiguityError: () => AggregatePriceAmbiguityError,
   AgriLogger: () => AgriLogger,
   AppError: () => AppError,
   ApprovalStatus: () => ApprovalStatus,
@@ -62,6 +63,7 @@ __export(index_exports, {
   OrderStatus: () => OrderStatus,
   PhysicalState: () => PhysicalState,
   PlantingMethod: () => PlantingMethod,
+  PriceAmbiguityError: () => PriceAmbiguityError,
   ProductType: () => ProductType,
   ProductUnit: () => ProductUnit,
   RESOURCE_MODULE_MAP: () => RESOURCE_MODULE_MAP,
@@ -90,10 +92,12 @@ __export(index_exports, {
   WaterSource: () => WaterSource,
   assertTenantBoundary: () => assertTenantBoundary,
   calculateFileMetadataMatch: () => calculateFileMetadataMatch,
+  createBase44PricingAdapter: () => createBase44PricingAdapter,
   decodeSession: () => decodeSession,
   encodeSession: () => encodeSession,
   evaluateBaseAccess: () => evaluateBaseAccess,
   extractAppCode: () => extractAppCode,
+  findOverlappingPriceWindows: () => findOverlappingPriceWindows,
   findSpecificOverride: () => findSpecificOverride,
   generateCanonicalId: () => generateCanonicalId,
   generateDocumentPath: () => generateDocumentPath,
@@ -115,6 +119,7 @@ __export(index_exports, {
   resolveAppError: () => resolveAppError,
   resolveEffectiveAccess: () => resolveEffectiveAccess,
   resolveError: () => resolveError,
+  resolvePrice: () => resolvePrice,
   transformRoleAssignments: () => transformRoleAssignments,
   verifyAndExtractSession: () => verifyAndExtractSession,
   withAgriLogging: () => withAgriLogging
@@ -247,6 +252,224 @@ function transformRoleAssignments(assignments) {
   return result;
 }
 
+// src/priceHelpers.ts
+var PriceAmbiguityError = class extends Error {
+  constructor(productId, tier, candidates, matchedOn = {}) {
+    const keyDescription = matchedOn.contractReferenceNumber ? `contract ${matchedOn.contractReferenceNumber}` : matchedOn.accountCode ? `account ${matchedOn.accountCode}` : "the system default";
+    super(
+      `Ambiguous pricing for product ${productId} at tier ${tier} (${keyDescription}): ${candidates.length} overlapping active prices found (${candidates.map((c) => `$${(c.unitPriceCents / 100).toFixed(2)}`).join(", ")}).`
+    );
+    this.productId = productId;
+    this.tier = tier;
+    this.candidates = candidates;
+    this.matchedOn = matchedOn;
+    this.name = "PriceAmbiguityError";
+  }
+  productId;
+  tier;
+  candidates;
+  matchedOn;
+};
+var AggregatePriceAmbiguityError = class extends Error {
+  constructor(productId, conflicts, shadowedCleanMatches = []) {
+    const tierList = conflicts.map((c) => c.tier).join(", ");
+    const note = shadowedCleanMatches.length > 0 ? ` Note: ${shadowedCleanMatches.length} other tier(s) had a clean price available but were not used, since a higher-priority tier must be resolved first.` : "";
+    super(
+      `Pricing for product ${productId} could not be resolved: ambiguous prices found at ${conflicts.length} tier(s) [${tierList}].${note}`
+    );
+    this.productId = productId;
+    this.conflicts = conflicts;
+    this.shadowedCleanMatches = shadowedCleanMatches;
+    this.name = "AggregatePriceAmbiguityError";
+  }
+  productId;
+  conflicts;
+  shadowedCleanMatches;
+};
+function fromMatrixRow(row, priceSource) {
+  return {
+    unitPriceCents: row.matrixUnitPriceCents,
+    minimumOrderQuantity: row.minimumOrderQuantity,
+    leadTimeDays: row.leadTimeDays,
+    priceSource,
+    sourceRecordId: row.canonicalId
+  };
+}
+async function resolvePrice(dataSource, context) {
+  const targetDate = context.evaluationDate ?? /* @__PURE__ */ new Date();
+  const conflicts = [];
+  const shadowedCleanMatches = [];
+  async function tryTier(lookup) {
+    try {
+      return await lookup();
+    } catch (err) {
+      if (err instanceof PriceAmbiguityError) {
+        conflicts.push(err);
+        return null;
+      }
+      throw err;
+    }
+  }
+  function handleCleanRow(row, tier, matchedOn) {
+    if (!row) return null;
+    if (conflicts.length === 0) return fromMatrixRow(row, tier);
+    shadowedCleanMatches.push({
+      tier,
+      unitPriceCents: row.matrixUnitPriceCents,
+      sourceRecordId: row.canonicalId,
+      matchedOn
+    });
+    return null;
+  }
+  if (context.contractReferenceNumber) {
+    const row = await tryTier(
+      () => dataSource.findContractPrice({
+        productId: context.productId,
+        contractReferenceNumber: context.contractReferenceNumber,
+        targetDate
+      })
+    );
+    const result = handleCleanRow(row, "EXPLICIT_CONTRACT", {
+      contractReferenceNumber: context.contractReferenceNumber
+    });
+    if (result) return result;
+  }
+  if (context.accountCode && context.accountCode !== "INTERNAL_DEFAULT") {
+    const row = await tryTier(
+      () => dataSource.findAccountPrice({
+        productId: context.productId,
+        accountCode: context.accountCode,
+        targetDate
+      })
+    );
+    const result = handleCleanRow(row, "ACCOUNT_MATRIX", { accountCode: context.accountCode });
+    if (result) return result;
+  }
+  const defaultRow = await tryTier(
+    () => dataSource.findDefaultPrice({ productId: context.productId, targetDate })
+  );
+  const defaultResult = handleCleanRow(defaultRow, "INTERNAL_DEFAULT", {});
+  if (defaultResult) return defaultResult;
+  if (conflicts.length > 0) {
+    throw new AggregatePriceAmbiguityError(context.productId, conflicts, shadowedCleanMatches);
+  }
+  const baseProduct = await dataSource.findBaseProduct({ productId: context.productId });
+  if (baseProduct) {
+    return {
+      unitPriceCents: baseProduct.unitPriceCents,
+      minimumOrderQuantity: 1,
+      leadTimeDays: null,
+      priceSource: "PRODUCT_FALLBACK",
+      sourceRecordId: baseProduct.canonicalId
+    };
+  }
+  throw new Error(`Critical Architecture Error: Product ${context.productId} not found in system catalog.`);
+}
+var ACTIVE_ROW_LOOKBACK = 5;
+var SORT_MOST_RECENT_FIRST = "-validFrom";
+function pickActiveRow(rows, targetIso, productId, tier, matchedOn) {
+  const activeMatches = rows.filter(
+    (r) => r.validTo === null || new Date(r.validTo).toISOString() >= targetIso
+  );
+  if (activeMatches.length > 1) {
+    throw new PriceAmbiguityError(
+      productId,
+      tier,
+      activeMatches.map((r) => ({
+        sourceRecordId: r.canonicalId,
+        unitPriceCents: r.matrixUnitPriceCents,
+        validFrom: r.validFrom,
+        validTo: r.validTo
+      })),
+      matchedOn
+    );
+  }
+  return activeMatches[0] ?? null;
+}
+function createBase44PricingAdapter(db, scope) {
+  const scopeFilter = {
+    authScopeId: scope.authScopeId,
+    ...scope.companyId ? { companyId: scope.companyId } : {}
+  };
+  return {
+    async findContractPrice({ productId, contractReferenceNumber, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        {
+          ...scopeFilter,
+          productId,
+          contractReferenceNumber,
+          matrixType: "procurement_buy",
+          validFrom_lte: targetIso
+        },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "EXPLICIT_CONTRACT", {
+        contractReferenceNumber
+      });
+    },
+    async findAccountPrice({ productId, accountCode, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        { ...scopeFilter, productId, accountCode, validFrom_lte: targetIso },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "ACCOUNT_MATRIX", { accountCode });
+    },
+    async findDefaultPrice({ productId, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        { ...scopeFilter, productId, accountCode: "INTERNAL_DEFAULT", validFrom_lte: targetIso },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "INTERNAL_DEFAULT", {});
+    },
+    async findBaseProduct({ productId }) {
+      const rows = await db.CompanyProduct.filter({ id: productId, authScopeId: scope.authScopeId });
+      return rows[0] ?? null;
+    }
+  };
+}
+function rangesOverlap(aFrom, aTo, bFrom, bTo) {
+  const aStart = new Date(aFrom).getTime();
+  const aEnd = aTo ? new Date(aTo).getTime() : Infinity;
+  const bStart = new Date(bFrom).getTime();
+  const bEnd = bTo ? new Date(bTo).getTime() : Infinity;
+  return aStart <= bEnd && bStart <= aEnd;
+}
+async function findOverlappingPriceWindows(db, scope, newRow, excludeId) {
+  const { productId, accountCode, contractReferenceNumber, matrixType, authScopeId, companyId } = scope;
+  const scopeFilter = {
+    authScopeId,
+    ...companyId ? { companyId } : {}
+  };
+  const existingRows = await db.ProductPriceMatrix.filter(
+    {
+      ...scopeFilter,
+      productId,
+      ...accountCode ? { accountCode } : {},
+      ...contractReferenceNumber ? { contractReferenceNumber } : {},
+      ...matrixType ? { matrixType } : {}
+    },
+    SORT_MOST_RECENT_FIRST,
+    // Write-time validation must see the product's full pricing history in
+    // this scope, not just rows near "now" — ACTIVE_ROW_LOOKBACK (5) is
+    // read-time-specific and too shallow here.
+    100
+  );
+  return existingRows.filter(
+    (r) => r.canonicalId !== excludeId && rangesOverlap(newRow.validFrom, newRow.validTo, r.validFrom, r.validTo)
+  ).map((r) => ({
+    sourceRecordId: r.canonicalId,
+    unitPriceCents: r.matrixUnitPriceCents,
+    validFrom: r.validFrom,
+    validTo: r.validTo
+  }));
+}
+
 // src/validators.ts
 var Validator = {
   /** * 1. Email: The classic. Uses a standard RFC 5322 regex.
@@ -436,7 +659,8 @@ var ERROR_DICTIONARY = {
   "400": { title: "Data Conflict", text: "A conflict occurred with an existing record. Please review and try again." },
   "402": { title: "Duplicate Entry", text: "A record with this name or identifier already exists." },
   "403": { title: "Edit Conflict", text: "This record was recently updated by someone else. Please refresh and try again." },
-  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." }
+  "404": { title: "Record In Use", text: "This record cannot be deleted because it is referenced by other data." },
+  "405": { title: "Pricing Conflict", text: "Multiple active prices were found for this product. An administrator must resolve the conflict before this price can be used." }
 };
 var UserRole = {
   OWNER: "owner",
@@ -1333,11 +1557,14 @@ var AppError = class extends Error {
   status;
   appCode;
   isOperational;
-  constructor(status, mod, cat, act, message) {
+  details;
+  // optional structured payload, e.g. conflicting price candidates
+  constructor(status, mod, cat, act, message, details) {
     super(message);
     this.status = status;
     this.appCode = `${mod}-${status}-${cat}${act}`;
     this.isOperational = true;
+    this.details = details;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -1346,15 +1573,21 @@ var ErrorFactory = {
   forbidden: (mod, act, msg = "Access denied") => new AppError(403, mod, CAT.PERMISSION, act, msg),
   badRequest: (mod, act, msg = "Bad request") => new AppError(400, mod, CAT.VALIDATION, act, msg),
   notFound: (mod, act = ACT.GENERIC, msg = "Record not found") => new AppError(404, mod, CAT.VALIDATION, act, msg),
-  conflict: (mod, act, msg = "Record already exists") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
-  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
+  conflict: (mod, act, msg = "Record already exists", details) => new AppError(409, mod, CAT.INTEGRITY, act, msg, details),
+  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation", details) => new AppError(409, mod, CAT.INTEGRITY, act, msg, details),
   subscription: (mod, msg = "Module locked or subscription required") => new AppError(403, mod, CAT.SUBSCRIPTION, ACT.GENERIC, msg),
   internal: (mod, msg = "Internal server error") => new AppError(500, mod, CAT.INTEGRITY, ACT.GENERIC, msg)
 };
 var handleAppErrorResponse = (error, mod = MOD.ADMIN) => {
   if (error instanceof AppError && error.isOperational) {
     return Response.json(
-      { error: { appCode: error.appCode, message: error.message } },
+      {
+        error: {
+          appCode: error.appCode,
+          message: error.message,
+          ...error.details ? { details: error.details } : {}
+        }
+      },
       { status: error.status }
     );
   }
@@ -1718,6 +1951,7 @@ function calculateFileMetadataMatch(criteria, fileMetadata, auditContext) {
   ACCESS_RANK,
   ACT,
   AccessLevel,
+  AggregatePriceAmbiguityError,
   AgriLogger,
   AppError,
   ApprovalStatus,
@@ -1757,6 +1991,7 @@ function calculateFileMetadataMatch(criteria, fileMetadata, auditContext) {
   OrderStatus,
   PhysicalState,
   PlantingMethod,
+  PriceAmbiguityError,
   ProductType,
   ProductUnit,
   RESOURCE_MODULE_MAP,
@@ -1785,10 +2020,12 @@ function calculateFileMetadataMatch(criteria, fileMetadata, auditContext) {
   WaterSource,
   assertTenantBoundary,
   calculateFileMetadataMatch,
+  createBase44PricingAdapter,
   decodeSession,
   encodeSession,
   evaluateBaseAccess,
   extractAppCode,
+  findOverlappingPriceWindows,
   findSpecificOverride,
   generateCanonicalId,
   generateDocumentPath,
@@ -1810,6 +2047,7 @@ function calculateFileMetadataMatch(criteria, fileMetadata, auditContext) {
   resolveAppError,
   resolveEffectiveAccess,
   resolveError,
+  resolvePrice,
   transformRoleAssignments,
   verifyAndExtractSession,
   withAgriLogging

package/dist/index.mjs

@@ -62,7 +62,7 @@ import {
   UserRole,
   VigorRating,
   WaterSource
-} from "./chunk-GZRAFNPA.mjs";
+} from "./chunk-Y5KVDVNY.mjs";
 
 // src/index.ts
 import { jwtVerify } from "jose";
@@ -192,6 +192,224 @@ function transformRoleAssignments(assignments) {
   return result;
 }
 
+// src/priceHelpers.ts
+var PriceAmbiguityError = class extends Error {
+  constructor(productId, tier, candidates, matchedOn = {}) {
+    const keyDescription = matchedOn.contractReferenceNumber ? `contract ${matchedOn.contractReferenceNumber}` : matchedOn.accountCode ? `account ${matchedOn.accountCode}` : "the system default";
+    super(
+      `Ambiguous pricing for product ${productId} at tier ${tier} (${keyDescription}): ${candidates.length} overlapping active prices found (${candidates.map((c) => `$${(c.unitPriceCents / 100).toFixed(2)}`).join(", ")}).`
+    );
+    this.productId = productId;
+    this.tier = tier;
+    this.candidates = candidates;
+    this.matchedOn = matchedOn;
+    this.name = "PriceAmbiguityError";
+  }
+  productId;
+  tier;
+  candidates;
+  matchedOn;
+};
+var AggregatePriceAmbiguityError = class extends Error {
+  constructor(productId, conflicts, shadowedCleanMatches = []) {
+    const tierList = conflicts.map((c) => c.tier).join(", ");
+    const note = shadowedCleanMatches.length > 0 ? ` Note: ${shadowedCleanMatches.length} other tier(s) had a clean price available but were not used, since a higher-priority tier must be resolved first.` : "";
+    super(
+      `Pricing for product ${productId} could not be resolved: ambiguous prices found at ${conflicts.length} tier(s) [${tierList}].${note}`
+    );
+    this.productId = productId;
+    this.conflicts = conflicts;
+    this.shadowedCleanMatches = shadowedCleanMatches;
+    this.name = "AggregatePriceAmbiguityError";
+  }
+  productId;
+  conflicts;
+  shadowedCleanMatches;
+};
+function fromMatrixRow(row, priceSource) {
+  return {
+    unitPriceCents: row.matrixUnitPriceCents,
+    minimumOrderQuantity: row.minimumOrderQuantity,
+    leadTimeDays: row.leadTimeDays,
+    priceSource,
+    sourceRecordId: row.canonicalId
+  };
+}
+async function resolvePrice(dataSource, context) {
+  const targetDate = context.evaluationDate ?? /* @__PURE__ */ new Date();
+  const conflicts = [];
+  const shadowedCleanMatches = [];
+  async function tryTier(lookup) {
+    try {
+      return await lookup();
+    } catch (err) {
+      if (err instanceof PriceAmbiguityError) {
+        conflicts.push(err);
+        return null;
+      }
+      throw err;
+    }
+  }
+  function handleCleanRow(row, tier, matchedOn) {
+    if (!row) return null;
+    if (conflicts.length === 0) return fromMatrixRow(row, tier);
+    shadowedCleanMatches.push({
+      tier,
+      unitPriceCents: row.matrixUnitPriceCents,
+      sourceRecordId: row.canonicalId,
+      matchedOn
+    });
+    return null;
+  }
+  if (context.contractReferenceNumber) {
+    const row = await tryTier(
+      () => dataSource.findContractPrice({
+        productId: context.productId,
+        contractReferenceNumber: context.contractReferenceNumber,
+        targetDate
+      })
+    );
+    const result = handleCleanRow(row, "EXPLICIT_CONTRACT", {
+      contractReferenceNumber: context.contractReferenceNumber
+    });
+    if (result) return result;
+  }
+  if (context.accountCode && context.accountCode !== "INTERNAL_DEFAULT") {
+    const row = await tryTier(
+      () => dataSource.findAccountPrice({
+        productId: context.productId,
+        accountCode: context.accountCode,
+        targetDate
+      })
+    );
+    const result = handleCleanRow(row, "ACCOUNT_MATRIX", { accountCode: context.accountCode });
+    if (result) return result;
+  }
+  const defaultRow = await tryTier(
+    () => dataSource.findDefaultPrice({ productId: context.productId, targetDate })
+  );
+  const defaultResult = handleCleanRow(defaultRow, "INTERNAL_DEFAULT", {});
+  if (defaultResult) return defaultResult;
+  if (conflicts.length > 0) {
+    throw new AggregatePriceAmbiguityError(context.productId, conflicts, shadowedCleanMatches);
+  }
+  const baseProduct = await dataSource.findBaseProduct({ productId: context.productId });
+  if (baseProduct) {
+    return {
+      unitPriceCents: baseProduct.unitPriceCents,
+      minimumOrderQuantity: 1,
+      leadTimeDays: null,
+      priceSource: "PRODUCT_FALLBACK",
+      sourceRecordId: baseProduct.canonicalId
+    };
+  }
+  throw new Error(`Critical Architecture Error: Product ${context.productId} not found in system catalog.`);
+}
+var ACTIVE_ROW_LOOKBACK = 5;
+var SORT_MOST_RECENT_FIRST = "-validFrom";
+function pickActiveRow(rows, targetIso, productId, tier, matchedOn) {
+  const activeMatches = rows.filter(
+    (r) => r.validTo === null || new Date(r.validTo).toISOString() >= targetIso
+  );
+  if (activeMatches.length > 1) {
+    throw new PriceAmbiguityError(
+      productId,
+      tier,
+      activeMatches.map((r) => ({
+        sourceRecordId: r.canonicalId,
+        unitPriceCents: r.matrixUnitPriceCents,
+        validFrom: r.validFrom,
+        validTo: r.validTo
+      })),
+      matchedOn
+    );
+  }
+  return activeMatches[0] ?? null;
+}
+function createBase44PricingAdapter(db, scope) {
+  const scopeFilter = {
+    authScopeId: scope.authScopeId,
+    ...scope.companyId ? { companyId: scope.companyId } : {}
+  };
+  return {
+    async findContractPrice({ productId, contractReferenceNumber, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        {
+          ...scopeFilter,
+          productId,
+          contractReferenceNumber,
+          matrixType: "procurement_buy",
+          validFrom_lte: targetIso
+        },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "EXPLICIT_CONTRACT", {
+        contractReferenceNumber
+      });
+    },
+    async findAccountPrice({ productId, accountCode, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        { ...scopeFilter, productId, accountCode, validFrom_lte: targetIso },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "ACCOUNT_MATRIX", { accountCode });
+    },
+    async findDefaultPrice({ productId, targetDate }) {
+      const targetIso = targetDate.toISOString();
+      const rows = await db.ProductPriceMatrix.filter(
+        { ...scopeFilter, productId, accountCode: "INTERNAL_DEFAULT", validFrom_lte: targetIso },
+        SORT_MOST_RECENT_FIRST,
+        ACTIVE_ROW_LOOKBACK
+      );
+      return pickActiveRow(rows, targetIso, productId, "INTERNAL_DEFAULT", {});
+    },
+    async findBaseProduct({ productId }) {
+      const rows = await db.CompanyProduct.filter({ id: productId, authScopeId: scope.authScopeId });
+      return rows[0] ?? null;
+    }
+  };
+}
+function rangesOverlap(aFrom, aTo, bFrom, bTo) {
+  const aStart = new Date(aFrom).getTime();
+  const aEnd = aTo ? new Date(aTo).getTime() : Infinity;
+  const bStart = new Date(bFrom).getTime();
+  const bEnd = bTo ? new Date(bTo).getTime() : Infinity;
+  return aStart <= bEnd && bStart <= aEnd;
+}
+async function findOverlappingPriceWindows(db, scope, newRow, excludeId) {
+  const { productId, accountCode, contractReferenceNumber, matrixType, authScopeId, companyId } = scope;
+  const scopeFilter = {
+    authScopeId,
+    ...companyId ? { companyId } : {}
+  };
+  const existingRows = await db.ProductPriceMatrix.filter(
+    {
+      ...scopeFilter,
+      productId,
+      ...accountCode ? { accountCode } : {},
+      ...contractReferenceNumber ? { contractReferenceNumber } : {},
+      ...matrixType ? { matrixType } : {}
+    },
+    SORT_MOST_RECENT_FIRST,
+    // Write-time validation must see the product's full pricing history in
+    // this scope, not just rows near "now" — ACTIVE_ROW_LOOKBACK (5) is
+    // read-time-specific and too shallow here.
+    100
+  );
+  return existingRows.filter(
+    (r) => r.canonicalId !== excludeId && rangesOverlap(newRow.validFrom, newRow.validTo, r.validFrom, r.validTo)
+  ).map((r) => ({
+    sourceRecordId: r.canonicalId,
+    unitPriceCents: r.matrixUnitPriceCents,
+    validFrom: r.validFrom,
+    validTo: r.validTo
+  }));
+}
+
 // src/validators.ts
 var Validator = {
   /** * 1. Email: The classic. Uses a standard RFC 5322 regex.
@@ -320,11 +538,14 @@ var AppError = class extends Error {
   status;
   appCode;
   isOperational;
-  constructor(status, mod, cat, act, message) {
+  details;
+  // optional structured payload, e.g. conflicting price candidates
+  constructor(status, mod, cat, act, message, details) {
     super(message);
     this.status = status;
     this.appCode = `${mod}-${status}-${cat}${act}`;
     this.isOperational = true;
+    this.details = details;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
@@ -333,15 +554,21 @@ var ErrorFactory = {
   forbidden: (mod, act, msg = "Access denied") => new AppError(403, mod, CAT.PERMISSION, act, msg),
   badRequest: (mod, act, msg = "Bad request") => new AppError(400, mod, CAT.VALIDATION, act, msg),
   notFound: (mod, act = ACT.GENERIC, msg = "Record not found") => new AppError(404, mod, CAT.VALIDATION, act, msg),
-  conflict: (mod, act, msg = "Record already exists") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
-  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation") => new AppError(409, mod, CAT.INTEGRITY, act, msg),
+  conflict: (mod, act, msg = "Record already exists", details) => new AppError(409, mod, CAT.INTEGRITY, act, msg, details),
+  integrity: (mod, act = ACT.GENERIC, msg = "Data integrity violation", details) => new AppError(409, mod, CAT.INTEGRITY, act, msg, details),
   subscription: (mod, msg = "Module locked or subscription required") => new AppError(403, mod, CAT.SUBSCRIPTION, ACT.GENERIC, msg),
   internal: (mod, msg = "Internal server error") => new AppError(500, mod, CAT.INTEGRITY, ACT.GENERIC, msg)
 };
 var handleAppErrorResponse = (error, mod = MOD.ADMIN) => {
   if (error instanceof AppError && error.isOperational) {
     return Response.json(
-      { error: { appCode: error.appCode, message: error.message } },
+      {
+        error: {
+          appCode: error.appCode,
+          message: error.message,
+          ...error.details ? { details: error.details } : {}
+        }
+      },
       { status: error.status }
     );
   }
@@ -704,6 +931,7 @@ export {
   ACCESS_RANK,
   ACT,
   AccessLevel,
+  AggregatePriceAmbiguityError,
   AgriLogger,
   AppError,
   ApprovalStatus,
@@ -743,6 +971,7 @@ export {
   OrderStatus,
   PhysicalState,
   PlantingMethod,
+  PriceAmbiguityError,
   ProductType,
   ProductUnit,
   RESOURCE_MODULE_MAP,
@@ -771,10 +1000,12 @@ export {
   WaterSource,
   assertTenantBoundary,
   calculateFileMetadataMatch,
+  createBase44PricingAdapter,
   decodeSession,
   encodeSession,
   evaluateBaseAccess,
   extractAppCode,
+  findOverlappingPriceWindows,
   findSpecificOverride,
   generateCanonicalId,
   generateDocumentPath,
@@ -796,6 +1027,7 @@ export {
   resolveAppError,
   resolveEffectiveAccess,
   resolveError,
+  resolvePrice,
   transformRoleAssignments,
   verifyAndExtractSession,
   withAgriLogging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litusarchieve18/agricore-utils",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Canonical Backend Utility Library for AgriCore",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",